home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Software Vault: The Gold Collection
/
Software Vault - The Gold Collection (American Databankers) (1993).ISO
/
cdr49
/
odoors41.zip
/
OPENDOOR.DOC
< prev
next >
Wrap
Text File
|
1993-04-05
|
535KB
|
12,634 lines
-----------------------------
OpenDoors
Door Programming Toolkit
Version 4.10
Programmer's Manual
-----------------------------
(C) Copyright 1991 - 1993 by Brian Pirie. All Rights Reserved.
NOTE: Since this manual is likely something that you will want to
refer to at the same time that you are working with
OpenDoors, looking at the sample source code, or writing
your own door and utility programs, it is highly recommended
that you take a moment to print it out. Simply type COPY
OPENDOOR.DOC PRN from your DOS prompt.
TABLE OF CONTENTS
TABLE OF CONTENTS .......................................2
CHAPTER 1 - INTRODUCTION TO OPENDOORS ...................4
WELCOME! ...........................................4
FEATURES OF THE OPENDOORS DOOR TOOLKIT .............4
CHAPTER 2 - ABOUT THE DEMO VERSION AND ORDERING .........7
THE DEMO VERSION & BENEFITS OF REGISTERING .........7
FILLING OUT THE REGISTRATION FORM ..................11
SENDING YOUR ORDER FEE .............................13
ORDERING THE SOURCE CODE ...........................15
ORDER FORM .........................................17
USER FEEDBACK FORM .................................19
CHAPTER 3 - LEARNING THE BASICS OF OPENDOORS ............20
ABOUT THIS MANUAL ..................................20
COMPILING A PROGRAM WITH OPENDOORS .................21
BASICS OF DOOR PROGRAMMING WITH OPENDOORS ..........23
A SAMPLE DOOR PROGRAM: "EZVOTE" ....................26
CHAPTER 4 - THE OPENDOORS DOORDRIVER FUNCTIONS ..........31
AN OVERVIEW OF THE FUNCTIONS .......................31
OD_CARRIER() .......................................35
OD_COLOUR_CONFIG() .................................37
OD_CLEAR_KEYBUFFER() ...............................39
OD_CLR_LINE() ......................................41
OD_CLR_SCR() .......................................43
OD_DISP() ..........................................45
OD_DISP_STR() ......................................47
OD_DRAW_BOX() ......................................49
OD_EDIT_STR() ......................................52
OD_EMULATE() .......................................63
OD_EXIT() ..........................................65
OD_GET_ANSWER() ....................................67
OD_GET_KEY() .......................................68
OD_HOTKEY_MENU() ...................................72
OD_INIT() ..........................................74
OD_INIT_WITH_CONFIG() ..............................77
OD_INPUT_STR() .....................................84
OD_KERNAL() ........................................86
OD_LIST_FILES() ....................................88
OD_LOG_OPEN() ......................................90
OD_LOG_WRITE() .....................................92
OD_PAGE() ..........................................93
OD_PRINTF() ........................................94
OD_PUTCH() .........................................98
OD_REPEAT() ........................................100
OD_SEND_FILE() .....................................102
OD_SET_ATTRIB() ....................................106
OD_SET_COLOUR() ....................................109
OD_SET_CURSOR() ....................................112
OD_SET_STATUSLINE() ................................114
OD_SPAWN() .........................................116
OD_SPAWNVPE() ......................................118
OpenDoors Door Toolkit Manual - Version 4.10 Page 2
CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE .............120
INTRODUCTION TO THE CONTROL STRUCTURE ..............120
CONTROL STRUCTURE - DOOR INFO FILE STATS ...........122
CONTROL STRUCTURE - MODEM SETTINGS .................125
CONTROL STRUCTURE - BBS AND CALLER INFORMATION .....126
CONTROL STRUCTURE - DOOR SETTINGS ..................147
CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION ........150
CONTROL STRUCTURE - FUNCTION KEYS ..................161
CONTROL STRUCTURE - COLOUR CUSTOMIZATION ...........164
CONTROL STRUCTURE - TEXT CUSTOMIZATION .............165
CHAPTER 6 - DEBUGGING OPENDOORS DOORS & GETTING HELP ....169
ABOUT THIS CHAPTER .................................169
TROUBLESHOOTING PROBLEMS ...........................169
SOLUTIONS TO COMMON PROBLEMS .......................171
OPENDOORS SUPPORT ..................................173
THE OPENDOORS SUPPORT BBS ..........................173
THE OPENDOORS ECHOMAIL CONFERENCE ..................174
GETTING IN TOUCH WITH ME ...........................174
OPENDOORS DISTRIBUTION SITES .......................176
JOINING THE DISTRIBUTION NETWORK ...................179
APPENDIX A - CONTENTS OF ARCHIVE ........................181
APPENDIX B - OPENDOORS HISTORY ..........................182
APPENDIX C - FUTURE VERSIONS ............................191
APPENDIX D - SPECIAL THANKS .............................192
GLOSSARY ................................................193
INDEX ...................................................201
OpenDoors Door Toolkit Manual - Version 4.10 Page 3
--------------------------------------------------------------------------------
CHAPTER 1 - INTRODUCTION TO OPENDOORS
--------------------------------------------------------------------------------
WELCOME!
--------------------------------------------------------------------------------
Welcome to OpenDoors! The OpenDoors door programming toolkit is a
powerful and easy to use door toolkit and BBS interface package
for Turbo C(++) and Borland C++ programmers. OpenDoors provides a
complete toolkit which allows you to EASILY and QUICKLY write
spectacular, professional quality BBS doors that automatically
support all of the popular BBS systems. With OpenDoors, you can
write door programs just as you would write any other program -
without having to worry about any of the internal details of door
programming. OpenDoors takes care of everything for you: It
handles all modem communications, ANSI/AVATAR graphics support
and BBS interfacing via door information files (such as DOOR.SYS,
DORINFO1.DEF, etc.). OpenDoors also looks after status lines and
sysop function keys for DOS shells, chatting, hanging up, etc..
In addition, OpenDoors carries out all of the work involved in
keeping track of carrier detection, user timeouts and much, much
more. Plus, OpenDoors is can be completely customized, allowing
you to take as little or as much control of your programs'
behaviour as you wish - and posing no limit on the possibilities
of what you can do with this package.
FEATURES OF THE OPENDOORS DOOR TOOLKIT
--------------------------------------------------------------------------------
OpenDoors is a complete "door driver" library that allows you to
write doors that DIRECTLY support one of the largest variety of
BBS systems, including RemoteAccess, QuickBBS, PC-Board, Maximus,
Opus, WildCat, WWIV, Spitfire, SuperBBS, Telegard, RBBS-PC,
TriTel, GAP and others. Interested in writing your own utility
doors? Perhaps on-line games? Would you even like to get into the
market of selling your doors for others to use? Or would you
simply like make your own BBS unique by running "custom" doors?
With OpenDoors, you can accomplish all of these things - and much
easier than ever before. Unlike other such "door drivers",
OpenDoors provides all of the following features:
- OpenDoors handles all of the "dirty" work involved in writing
door programs. Interested in writing doors for BBSes, either
your own, or to distribute (even sell!) to other people? Since
OpenDoors handles all of the door-related operations for you,
you need do next to nothing different when writing door
programs than you would when writing any other program. You
simply call OpenDoors' simple functions to input, output and
control door operation. In fact, many people have converted
OpenDoors Door Toolkit Manual - Version 4.10 Page 4
non-door programs to door programs in only a matter of minutes
using OpenDoors. One of the most common comments I receive
about OpenDoors is how easy it is to use.
- As you would expect, OpenDoors flawlessly monitors carrier
detect functions, to automatically recover when a user drops
carrier - without your having to do anything extra in your
program. OpenDoors also monitors how much time the user has
left in the door, and provides a fully-adjustable inactivity
timeout monitor.
- OpenDoors takes care of all the work involved in reading and
writing BBS door information files, such as DORINFO1.DEF,
EXITINFO.BBS, CHAIN.TXT, DOOR.SYS, etc. If the particular
information is available to OpenDoors, it will provide you
with just about everything you could ever want to know about
the user on-line, the system your door is running under, and
so on.
- OpenDoors also does all the work involved in displaying and
automatically updating the door's RemoteAccess-style status
line, with information available to the sysop such as user
name, location, baud rate, time left, function keys, ANSI and
AVATAR settings, and so on. OpenDoors even keeps track of a
user "wants-chat" indicator, just like the one in
RemoteAccess, QuickBBS and other BBS systems.
- OpenDoors automatically provides the sysop with all the
standard function keys for adjusting user time, hanging up on
or even locking out the user, and so on. OpenDoors also
provides you with a chat mode, which is available to the sysop
by pressing Alt-C. In addition, the door driver has full
support for sysop shell to DOS, activated by the Alt-J key.
- What's more, OpenDoors is designed to be very easy to use.
Even the most novice `C' programmers are able to write
professional-quality doors with OpenDoors. It takes care of
just about every detail for you, yet still gives you the
ability to completely control and customize every detail of
your door's behaviour. There are even people who begin door
programming with OpenDoors, having never programmed in C in
the past.
- OpenDoors has full support for locked baud-rates of up to
38,400 baud, using the FOSSIL driver for maximum compatibility
with any system. To output text in your door, you simply call
one print function. This function looks after all
communication with the modem, and also echos the output to the
local screen (referred to as twining the output). OpenDoors
also automatically detects if the BBS is operating in local
mode, and will function as expected.
- Other OpenDoors functions include a built in sysop-page
function that will ask the user why they wish to chat, and
then proceed to page the sysop, just as any BBS package would.
OpenDoors also provides screen clearing functions (which will
OpenDoors Door Toolkit Manual - Version 4.10 Page 5
detect whether the user has screen clearing turned on), and
various ANSI/AVATAR control functions (which again detect if
the user has graphics mode turned on).
- As if this weren't enough OpenDoors is also DesqView aware.
When OpenDoors starts up, it will automatically check for the
presence of DesqView, and if available, will perform all of
it's screen output through DesqView.
- OpenDoors has a number of special sub-systems that you may
elect to include in your doors. Among these, are a log-file
system that allows you to add log file support to your doors
with only a single line of programming.
- Another valuable OpenDoors sub-system is the configuration
file system. Again using only a single line of code, you can
add configuration file support to your doors. OpenDoors
configuration files permit the sysop using the door to
customize the door's performance to their own preferences.
Among the settings available in the configuration file are
system directories, screen colours, maximum time permitted
within the door, sysop paging hours, memory swapping options.
The sysop can also specify a custom door information file
(drop file) format, to allow your doors to operate on
literally ANY BBS system.
- OpenDoors can also be fully customized in order that you may
write door programs that use languages other than English.
- Among the ANSI / AVATAR features found in OpenDoors is the
ability to send ANSI / AVATAR files from disk. This allows you
to easily design program screens, and incorporate them into
your doors.
- OpenDoors also comes with the source code for a user-voting
door, EZVOTE, that you can modify, or simply extract bits and
pieces for use in your own doors. Plus, this manual contains
many examples of C source code, to help you in writing nearly
any door program you might wish to build. A number of other
example programs are also included with the package.
- You may also elect to purchase the source code for OpenDoors,
which will permit you to make modifications to any portion of
OpenDoors, use any portions of the OpenDoors source code in
other programs you write, or merely learn how communications-
type programs are written.
OpenDoors Door Toolkit Manual - Version 4.10 Page 6
--------------------------------------------------------------------------------
CHAPTER 2 - ABOUT THE DEMO VERSION AND ORDERING
--------------------------------------------------------------------------------
THE DEMO VERSION & BENEFITS OF REGISTERING
--------------------------------------------------------------------------------
This archive contains the demo version of OpenDoors. This version
has all the features of the registered version, but can only be
used under limited circumstances:
1.) The demo (unregistered) version may only be used for a
reasonable evaluation period, for evaluation purposes.
2.) Programs written in this version may not be distributed.
Also, any program written in the demo version will display a
message to the user indicating that it is not registered. This
message is, of course, removed in the registered version.
If you decided to purchase OpenDoors, you will become the owner
of a powerful tool for creating BBS door and utility programs.
Registered owners of OpenDoors are entitled to:
1.) Unlimited use of OpenDoors. You may write as many programs as
you wish using OpenDoors, and do what you please with these
programs. They may be freely distributed, or even sold.
What's more, there are no additional royalty fees. Your one
time purchase of OpenDoors entitles you to use it as you
please.
2.) You also be entitled to free upgrades to newer versions of
OpenDoors. In addition to the great many features and the
quality that this version of OpenDoors has to offer, I am
currently working on a great many additions and enhancements
for the next version. (See the end of this document for an
outline of features currently "in the works") Any programs
you write in this version will also automatically take on
these new features when you receive the new version.
The best news of all is how cheap OpenDoors is! Other "door-
drivers" sell for $50, $75, or even more! However, this version
of OpenDoors will only cost you $28! (Also, you may be interested
in knowing that the price will go up in future versions, so if
you register now, you will save by getting ALL future upgrades
for free.)
Also, the source code for OpenDoors is now available to
registered users for an additional $28! Ordering a copy of the
source code will allow you to customize OpenDoors for your own
use, making any changes or additions that you wish. It also gives
OpenDoors Door Toolkit Manual - Version 4.10 Page 7
you the opportunity to see how OpenDoors works, and to use any
portions of the OpenDoors code in any other programs you wish to
write. If you think you might be interested in ordering the
OpenDoors source code, please be sure to read the section
entitled "Ordering The Source Code", located on page 15.
OpenDoors Door Toolkit Manual - Version 4.10 Page 8
HOW TO ORDER
--------------------------------------------------------------------------------
PLEASE Below are detailed instructions for registering OpenDoors.
NOTE These instructions are not intended to seem confusing or
complicated; they are simply meant to answer almost any question
that you might have about registering. However, note that it is
probably not necessary for you to worry about whether you are
following these steps to the letter - I'm not that picky. So long
as you send your registration form and fee by some means, there
should not be any difficulty in processing your registration. If
you do have any questions or uncertainties about your
registration, please feel more than free to contact me. For
information on how to contact me, please see page 173.
To order OpenDoors, simply follow these three steps:
1.) Fill out the registration form. Information on filling out
the form is located on page 11.
2.) Send the appropriate payment, $28 for the registration or
$56 for both the registration and source code. If you wish
more detailed instructions on sending the registration fee,
see the section that begins page on 13.
3.) Send the above two items (along with a diskette and envelope
if you are ordering the source code, and wish to receive it
by mail) to me at:
Brian Pirie
Apt. 1416 - 2201 Riverside Dr.
Ottawa, Ontario
Canada
K1H 8K9
If you think you might also be interested in the OpenDoors source
code, be sure to read the section on the source code, which
begins on page 15.
Keep in mind that the registration form in this package is only
used for registering the OpenDoors door toolkit. If you are also
using the OpenDoors BBS interface package, you must register it
by sending the separate registration form contained in that
package. However, if you have both packages and wish to register
both of them at the same time, you may send both registrations
together, and must only make out a single cheque for the total of
both registrations.
Also, you may wish to send the OpenDoors feedback form (located
on page 18), along with your registration. The feedback form
gives you a chance to tell me what you think about OpenDoors, and
OpenDoors Door Toolkit Manual - Version 4.10 Page 9
what changes you would like to see in future versions. In fact,
the majority of suggestions made on suggestion forms in the past
have already been implemented in more recent versions of
OpenDoors.
OpenDoors Door Toolkit Manual - Version 4.10 Page 10
FILLING OUT THE REGISTRATION FORM
--------------------------------------------------------------------------------
If you have printed the OpenDoors manual, you can simply remove
and mail the forms on pages 17 and 18. If you have not already
printed a copy of the manual, and you have a printer, you can
quickly print these forms by printing the ORDER.FRM file included
in the OpenDoors distribution archive. (Type COPY ORDER.FRM PRN
from your DOS prompt.)
NO PRINTER? Alternatively, if you do not have a printer, simply send a hand-
drawn version of the order form.
If you have any special instructions for me, or anything that you
would like to say when you register, feel free to write this down
on the back of the registration form, or on a separate piece of
paper.
When filling out the OpenDoors registration form, be sure to
indicate how you would prefer to receive your OpenDoors
registration key and/or source code. You will have the choice of
receiving your registration key and/or source code by one of
three means: conventional mail, FidoNet CrashMail, or by a call
to your BBS. Although I try to send all orders the same day that
I receive your order form, if you have a FidoNet Email address,
FidoNet CrashMail is still by far the quickest way to receive
your order. Once you have decided which means you would prefer to
receive your order by, please read the detailed instructions on
your order method, below. Also, if you are ordering the source
code, please be sure to read the section which begins on page 15.
--------------------------------------------------------------------------------
RECEIVING In order to receive your OpenDoors registration key and/or
ORDER source code by conventional mail, simply fill out the order
BY MAIL form and mail it along with your payment as described below. I
will cover the cost of postage. If you are ordering the source
code (requiring the mailing of a diskette), or your address
contains non-Arabic characters, also enclose a self-addressed
envelope.
If you are also ordering the source code, please be sure to
enclose either a 5-1/4" 360K or 3-1/2" 720K/1.44M floppy disk.
--------------------------------------------------------------------------------
RECEIVING In order to receive your OpenDoors registration key and/or
BY CALL source code by a message and/or upload to your BBS, fill out
TO BBS the order form and mail it along with your payment as described
below. Be sure to include the phone number, baud rate, and my
login and password for the BBS to which you would like me to
call. As always, I will cover any long distance costs. If, for
OpenDoors Door Toolkit Manual - Version 4.10 Page 11
some reason, I am unable to connect to your BBS (not because it
is busy, but, for example, if your BBS is no longer online), I
will send your order by conventional mail instead.
--------------------------------------------------------------------------------
RECEIVING In order to receive your OpenDoors registration key and/or
ORDER BY source code by FidoNet CrashMail, simply fill out the order
FIDONET form and mail it along with your payment as described below.
CRASHMAIL Be sure to include the FidoNet node address to which you wish to
have your registration key and/or source code sent to (via
CrashMail). Again I will cover any long distance costs. If, for
some reason, I am unable to connect to your FidoNet system, I
will send your order by conventional mail instead.
OpenDoors Door Toolkit Manual - Version 4.10 Page 12
SENDING YOUR ORDER FEE
--------------------------------------------------------------------------------
As mentioned before, the OpenDoors registration fee is only $28
in either Canadian or U.S. currency, or the equivalent in funds
from any other country. You may also elect to receive the
OpenDoors source code for an additional $28 (ie. $56 for both
your OpenDoors registration, and the source code). I are able to
accept your order fee in any of the following forms:
-Cheque or Money Order in Canadian currency, drawn upon a
Canadian bank. In this case, your order fee will be either
$28CDN for just the registration, or $56CDN for both the
registration and source code.
-Cheque or Money Order in U.S. currency, drawn upon a U.S. bank.
In this case, your order fee will be either $28US for just the
registration, or $56US for both the registration and source
code.
-An International Money Order or International Bank Draft
(available from your bank, post office or organization such as
American Express), in Canadian currency. Depending on the
particular case, your order fee MAY be sent to me by the postal
service, and you will mail your order form by itself. You
should have the money order drawn in either $28CDN for just the
registration, or $56CDN for both the registration and source
code.
-A cheque drawn on any bank in the world, IN THAT COUNTRIES
CURRENCY, equivalent to 28 Canadian or U.S. dollars. For
instance, a cheque for the appropriate number of British
Pounds, drawn on a British bank, is perfectly acceptable.
However, I am unable to accept a cheque for $28 Canadian
dollars, drawn on a British Bank.
-Cash, $28 for the just registration, or $56 for both the
registration and source code, in either Canadian or U.S.
currency. Please note that it is not usually recommended that
cash be sent in the mail, and that I cannot be responsible for
any cash lost in the mail. Simply put, if you wish to order by
cash, it is your responsibility to get the cash to me. However,
if I do receive your order in the form of cash, it will be
perfectly acceptable to me. I would like to mention that many
people have already ordered OpenDoors by sending cash, and I
have yet to run across any case of cash being lost in the mail.
Nonetheless, if you wish to send cash, you may wish to consider
doing so by registered mail, for your added security.
If you are ordering OpenDoors from within Canada, you will most
likely choose the first option (a Canadian cheque or money
OpenDoors Door Toolkit Manual - Version 4.10 Page 13
order). If you are ordering OpenDoors from within the United
States, you will most likely choose the second option (an
American cheque or money order). If you are ordering from outside
Canada and the U.S., it would be ideal if you could send your fee
by an international money order. However, it should be noted that
any of the above order methods will be acceptable from any
location. Also, it is quite possible that I may be able to accept
other means of sending your order fee. If you are unsure about
sending your order fee, please feel free to get in touch with me
by any of the means listed on page 173.
OpenDoors Door Toolkit Manual - Version 4.10 Page 14
ORDERING THE SOURCE CODE
------------------------------------------------------------------------------
There are many benefits to also ordering the source code along
with your OpenDoors registration. Ordering the source code will
allow you to customize OpenDoors for your own use, use parts of
the OpenDoors source code in other programs, and learn more about
how OpenDoors works. If you have any ideas for changes that you
would like to see in OpenDoors, either large or small, ordering
the source code will allow you to makes these changes yourself,
creating your own customized version of OpenDoors. You will be
able to remove copyright notices, change the way certain
OpenDoors functions work, or add new capabilities to OpenDoors in
surprisingly little time. You will also be able to use any of the
OpenDoors source code, be it the DesqView-aware code, EMS/disk
swapping routines, configuration file system, communications
routines, or anything else, in any other programs that you may
wish to write. Also, ordering the OpenDoors source code will
allow you to learn more about how OpenDoors works, and how to
program communications software, door programs, BBS utilities,
and so on.
As mentioned before, registered users may order the OpenDoors
source code for an additional $28, either at the same time you
register OpenDoors, or separately. If you wish to order the
OpenDoors source code, simply indicate on your order form that
you wish to order both your OpenDoors registration, and your
source code, and include the additional fee for ordering the
source code.
When you order the OpenDoors source code, you will receive the
source code package. The source code package includes all of the
source code, with the exception of the registration key decoding
algorithm. This small piece of code is instead included in the
form of .OBJect files, one for each memory model. The source code
package also includes a short "Source Code Manual", with a
description of how the OpenDoors source code is organized,
instructions on how to recompile the source code, and more. In
addition, the source code package includes a full set of batch
files for automatically re-compiling the OpenDoors libraries.
In order to re-compile the OpenDoors source code, we would
recommend that you have Turbo C++ 1.00 or later, or any version
of Borland C++. If you are using Turbo C 2.00 or earlier, you
will have to make a few minor alterations to the source code in
order to re-compile it with your compiler.
Also, as with your OpenDoors registration, when you order the
OpenDoors source code, you are entitled to receive all future
versions of the source code.
OpenDoors Door Toolkit Manual - Version 4.10 Page 15
IMPORTANT If you wish to order the source code there are a few important
things which you should note. First of all, if you choose to
receive your source code by mail (as opposed to upload to your
BBS, or FidoNet CrashMail), be sure to enclose a Double-Density
5-1/4" diskette with mailing envelope, or either Double-Density
or High-Density 3-1/2" diskette. Also, due to the costs of over-
seas long distance, an extra $15 is required in order to send the
OpenDoors source code by BBS upload or FidoNet CrashMail to any
sites outside of North America. There is no extra cost for
sending the source code by BBS upload or FidoNet CrashMail within
North America. Nor is there any extra cost for having it sent by
conventional mail in or outside North America.
OpenDoors Door Toolkit Manual - Version 4.10 Page 16
---------------------------------------------------------------------------
OPENDOORS DOOR PROGRAMMING TOOLKIT 4.10 - ORDER FORM
---------------------------------------------------------------------------
YOUR NAME : _______________________________ (AS SHOULD APPEAR IN
REGISTRATION)
POSTAL ADDRESS : ______________________________________________________
______________________________________________________
VOICE PHONE NUMBER : ______________________
NETWORK ADDRESSES : ____________________________________ (IF APPLICABLE)
BBS PHONE NUMBER : ______________________ (IF APPLICABLE)
BEST TIME TO CALL : __________________ BRIAN'S PASSWORD : __________
(ONLY IF YOU WISH TO RECEIVE YOUR ORDER BY A MESSAGE ON YOUR BBS)
___
I WISH TO RECEIVE MY ORDER BY: | | - FIDONET "CRASHMAIL"
|___|
___
| | - CALL TO MY BBS
|___|
___
| | - CONVENTIONAL MAIL
|___|
___
I WOULD LIKE TO ORDER: | | - JUST MY REGISTRATION KEY, FOR $28
|___|
___
| | - JUST THE SOURCE CODE (ONLY IF ALREADY
|___| REGISTERED), FOR $28
___
| | - BOTH REGISTRATION KEY AND SOURCE CODE,
|___| FOR $56
I HAVE ALSO SENT THE APPROPRIATE ORDER FEE, PAYABLE TO BRIAN PIRIE.
____________________________
(SIGNATURE)
MAIL TO: BRIAN PIRIE
APT. 1416 - 2201 RIVERSIDE DR.
OTTAWA, ONTARIO
CANADA
K1H 8K9
+-- OFFICE USE ONLY ------------------------------------------------------+
| |
| Rcvd : _______ Date : _________ S.N. : _________ Key : _____________ |
+-------------------------------------------------------------------------+
OpenDoors Door Toolkit Manual - Version 4.10 Page 17
---------------------------------------------------------------------------
OPENDOORS DOOR PROGRAMMING TOOLKIT 4.10 - USER FEEDBACK FORM
---------------------------------------------------------------------------
YOUR NAME : _______________________________
POSTAL ADDRESS : ______________________________________________________
______________________________________________________
VOICE PHONE NUMBER : ______________________
NETWORK ADDRESSES : ____________________________________ (IF APPLICABLE)
WHERE DID YOU RECEIVE YOUR COPY OF OPENDOORS?
____________________________________________________________
WHICH COMPILER AND VERSION ARE YOU USING? (EG. BORLAND C++ 3.00)
____________________________________________________________
WHAT DO YOU LIKE MOST ABOUT OPENDOORS?
____________________________________________________________
____________________________________________________________
____________________________________________________________
WHAT CHANGES OR ADDITIONS WOULD YOU LIKE TO SEE IN FUTURE VERSIONS?
____________________________________________________________
____________________________________________________________
____________________________________________________________
DO YOU HAVE ANY ADDITIONAL COMMENTS?
____________________________________________________________
____________________________________________________________
____________________________________________________________
------------------------------------------------------------------------------
OpenDoors Door Toolkit Manual - Version 4.10 Page 18
------------------------------------------------------------------------------
CHAPTER 3 - LEARNING THE BASICS OF OPENDOORS
------------------------------------------------------------------------------
ABOUT THIS MANUAL
------------------------------------------------------------------------------
The OpenDoors programmer's manual is intended to serve as a
complete tutorial, guide and reference to writing programs with
OpenDoors. Chapter 1 of this manual, beginning on page 4, serves
as an introduction and overview of the features of OpenDoors.
Chapter 2, beginning on page 7, then contains all of the
information related to this demo version of OpenDoors, and how to
register your copy. This chapter then serves as a tutorial on
OpenDoors and door programming in general. Chapter 4 then deals
with the functions which OpenDoors provides for door programming.
Chapter 5 deals with the "OpenDoors control structure", which
gives you access to a wide array of information, and allows you
to customize OpenDoor's appearance and behaviour.
Chapter 6 (which begins on page 168) is perhaps the most
important single part of this manual. This chapter gives detailed
instructions on troubleshooting programs written with OpenDoors,
lists solutions to common difficulties, and has information about
the many sources for OpenDoors support. If at any time you are
having difficulty with OpenDoors, be sure to refer to this
chapter for complete step-by-step instruction on tracing the
source of your problem, and for solutions to common difficulties
with OpenDoors. This chapter also directs you to some of the many
means of OpenDoors support, including information on the
OpenDoors EchoMail conference, the OpenDoors support BBS, and how
to get in touch with me.
You will also find many useful tools in this manual, which will
no doubt come in useful while working with OpenDoors. Beginning
on page 2 is a basic table of contents, showing you have the
manual is organized, and helping you to locate general topics. At
the end of the manual, beginning on page 200, is an index to help
you locate more information on specific topics. The manual also
includes a glossary, on page 192, which will help you in
understanding new terms that you may come across while reading
the manual. At the end of the manual, you will also find several
useful section, such as a brief history of OpenDoors, information
on how to contact us, and information about new OpenDoors
features currently in the works.
It is suggested that if you wish to get the most out of
OpenDoors, that you carefully read the sections of the manual
that describe the use of the features you are using, and at least
skim other portions of the manual to find out what additional
features are available. Also, you will likely want to print this
manual, to make reading and reference while programming easier.
OpenDoors Door Toolkit Manual - Version 4.10 Page 19
To print this manual, simply type the following line from your
DOS prompt:
COPY OPENDOOR.DOC PRN:
COMPILING A PROGRAM WITH OPENDOORS
--------------------------------------------------------------------------------
The process of compiling a program written with OpenDoors is very
similar to that of compiling any other program. However, there
are two additional steps which you must be sure to remember:
1.) To include the OPENDOOR.H header file.
2.) To link your program with the appropriate OpenDoors library
file.
All programs written with OpenDoors, must "include" the
OPENDOOR.H header file. This is easily accomplished by placing
the line #include "OPENDOOR.H" at the beginning of your program's
.C file.
You must also "link" the OpenDoors library file with your
program. The recommended way of doing this is by including the
appropriate library in your project file. If you are unfamiliar
with the process of using project files, please refer to your
Turbo C(++)/Borland C++ manuals. Simply put, if you are using
Turbo C, you should create a text file with a .PRJ file, and list
in this text file the name of your program's .C file, along with
the name of the appropriate library file. You should then select
this .PRJ project file from within Turbo C, prior to compiling
your program. If you are using Turbo C++ or Borland C++, you can
create a project file by selecting the "Open" command from the
"Project" menu. Simply type in the name of a new .PRJ project
file to create, and then "Add" the name of your program's .C
file, along with the name of the appropriate OpenDoors library.
Again, whenever you wish to compile your program simply load the
project file for that program first.
There are a number of different library files included with
OpenDoors, one for each memory model. The following chart lists
the library file names, along with their corresponding memory
model. It is important that you use the library file which
corresponds to the memory model you are using.
If you are unfamiliar with the concept of memory models, you
should refer to your C programming manuals. Simply put, within
Turbo C(++)/Borland C++, you must select the memory model you
wish to use when compiling your program. In order for your
program to compile correctly, you must also include the library
file which corresponds to the memory model you have selected.
OpenDoors Door Toolkit Manual - Version 4.10 Page 20
+------------------------------------------------+
| Library | Memory |
| Filename | Model |
+-------------+----------------------------------|
| ODOORS.LIB | The Small memory model library |
| | |
| ODOORM.LIB | The Medium memory model library |
| | |
| ODOORC.LIB | The Compact memory model library |
| | |
| ODOORL.LIB | The Large memory model library |
| | |
| ODOORH.LIB | The Huge memory model library |
+------------------------------------------------+
For more information on including third-party libraries in your
programs, please also see your Turbo C(++) / Borland C++ manuals.
OpenDoors Door Toolkit Manual - Version 4.10 Page 21
BASICS OF DOOR PROGRAMMING WITH OPENDOORS
--------------------------------------------------------------------------------
This section provides a complete tutorial to the basics of door
programming with OpenDoors. It is important that you read this
section, as while OpenDoors allows you to write door programs in
almost the same manner as you would any "normal" program, there
are a few things which you must keep in mind, in order that your
door functions correctly. We would also encourage you to look at
the sample door included with OpenDoors, EZVote. This program,
which is described beginning on page 25, will give you a much
better idea of what an OpenDoors door will look like, and
provides you with a starting point for writing your own doors.
Perhaps the best means of introduction to door programming with
OpenDoors is by doing it yourself. As such, it would probably be
a good idea for you to try typing in, compiling and running the
simple introduction program below. For instructions on compiling
programs written with OpenDoors, see page 20.
#include "opendoors.h"
main()
{
od_printf("Welcome to my first Door!\n\r");
od_printf("Press a key to return to BBS!\n\r");
od_get_key(TRUE);
od_exit(10,FALSE);
}
Keep in mind that even this simple program will automatically
have all of the door capabilities we have already mentioned.
Notice the inclusion of the OPENDOOR.H file. All doors written
with OpenDoors must include the OPENDOOR.H header file in order
to compile correctly. The first two lines in the main function
simply call the OpenDoors printf function (which sends the output
to both the modem and the local screen). Notice that the strings
displayed by the od_printf() function end with a "\n\r" sequence,
instead of the normal "\n". The next line is the OpenDoors
single-key input function. The TRUE value causes the system to
wait for a key to be pressed (again, either from remote or local
keyboard). The last line of the main function then ends the door,
returning an errorlevel of 10. The FALSE indicates that you do
not wish to have OpenDoors terminate the call (hang up on the
user). If you placed a TRUE in its place, then a remote user
would be logged off when the door exits. We would strongly
encourage you to try compiling and running this program on your
own BBS setup. For information on compiling programs with
OpenDoors, see the section beginning on page 20. Congratulations,
you have written your first door! Feel free to make any changes
to this program, and see what effects your changes have.
OpenDoors Door Toolkit Manual - Version 4.10 Page 22
In case you are not completely familiar with the operation of
door programs, we will now provide an introduction to the
internals of a door's operation. Keep in mind that OpenDoors
automatically carries out most of these tasks for you. When any
door program starts up, one of the first things it must do is to
read the door information file(s) passed to it by the BBS . When
a user is on-line, and wishes to run a door, they will most
likely select a command from a menu. At this point, the BBS
system (such as RemoteAccess, Maximus, or whatever), will create
a file of information about the system, who is on-line, and so
on. Various BBS packages produce various styles of door
information files. OpenDoors recognizes a wide variety of door
information files, and future versions will recognize others. As
a result, your doors will be able to run on a great many
different BBS systems.
The door itself will actually be loaded in one of two manners.
Either the BBS will perform a "shell" and run the door while the
BBS system resides in memory (sometimes called a type 7 exit), or
it will exit to a batch file, which will trap an errorlevel and
load the appropriate door. (sometimes called a type 15 exit). In
either case, when the door gains control, it will first read the
door information file(s), and then begin to communicate with the
modem. OpenDoors, as with almost all other BBS software, performs
all of its modem communication with the "FOSSIL driver". The
FOSSIL driver is loaded either as a .SYS device driver from
Config.Sys at boot-up, or from an .EXE file as a TSR program, and
provides the BBS software with a standard interface layer for
communicating with just about any type of modem. Hence, whenever
your door is not running in local mode, it will require a FOSSIL
driver, such as X00 or BNU to be loaded.
Fortunately, OpenDoors takes care of all the work involved in
detecting and reading the door information file, and then
initializing and communicating with the FOSSIL driver for you. In
order to carry out these tasks, along with setting up the status
line, and so on, OpenDoors provides a function called od_init();.
If you do not explicitly call this function, the first call to
any other OpenDoors DOOR DRIVER function (such as the first time
your door program outputs anything) will automatically cause the
od_init function to be called. As a result, upon the first call
to an OpenDoors DOOR DRIVER function (but not BBS interface
module functions), all of the initialization tasks for the door
will automatically be carried out. However, there may be times
when you will want your program to have access information about
the user who is on-line, or carry out other actions which require
od_init() to have been executed - prior to the point where you
call any other OpenDoors functions. In this case, you will have
to call od_init() yourself before you do any of these things.
OpenDoors provides you with a C structure, by the name of
od_control, which allows you to access all the available
information about the user who is on-line, the system your door
is running on, and also allows you to adjust various OpenDoors
parameters. Depending on what BBS system your door is running
under, the actual information available from the od_control
OpenDoors Door Toolkit Manual - Version 4.10 Page 23
structure will vary. For more information on the od_control
structure, see the section on the control structure, beginning on
page 119.
Once the door has initialized itself, it will then begin
communications with the user who is online. OpenDoors takes care
of all communications, through its various input and display
functions. When the door has finished, it will then write any
information that has changed back to the door information file
(if applicable), finish communicating with the modem, and return
to the BBS. In OpenDoors, this is accomplished with the od_exit()
function. This function will terminate the door's activity,
OPTIONALLY hang up on the user (allowing you to provide either
return to BBS or logoff options for exiting), and then exit with
the specified errorlevel. You *MUST* exit your door by calling
the od_exit() function.
One other important OpenDoors function that you should be aware
of is the od_kernal() function. od_kernal() is the central
OpenDoors control function, and is responsible for much of
OpenDoors' updating of the status line, monitoring the carrier
detect and user timeout status, responding to sysop function
keys, and so on. The od_kernal() function is called automatically
by OpenDoors, within the other OpenDoors door driver functions.
As a result, since most door programs will call some OpenDoors
function on a regular basis, you will most often have no need to
call the od_kernal() function yourself. However, if your door is
going to perform some action, such as updating data files, during
which it will not call any OpenDoors door driver function for
more than a few seconds, you should then call the od_kernal()
function yourself. For more information on the od_kernal()
function, see page 85.
For more information on the functions available from OpenDoors,
or the control structure, see the corresponding sections in this
manual. We would also suggest that you have a look at the sample
door included with OpenDoors, EZVote.
OpenDoors Door Toolkit Manual - Version 4.10 Page 24
A SAMPLE DOOR PROGRAM: "EZVOTE"
-------------------------------------------------------------------------------
One of the best ways to see how OpenDoors works, and the
potential that it has, is to look at the source code for the
included sample door, EZVote. While this is by no means a complex
door, it should certainly give you a clear impression of how
OpenDoors doors are built, and will likely give you many ideas
for your own doors. You can run the door as included in the
archive by typing EZVOTE (the archive also contains a sample
DORINFO1.DEF file, which will allow you to test any doors in
local mode.) If you wish to manually create your own DORINFO1.DEF
file, you can do so very easily. The DORINFO1.DEF door
information file is a simple text file which lists a different
piece of information on each line, in the following format:
+----------------------------------------------------------+
| LINE NUMBER | DESCRIPTION | EXAMPLE |
+-------------+------------------------+-------------------|
| 1 | Name of the BBS | MY OWN BBS |
| 2 | Sysop's first name | BRIAN |
| 3 | Sysop's last name | PIRIE |
| 4 | Com Port modem is on | COM0 |
| 5 | Baud rate, etc. | 0 BAUD,N,8,1 |
| 6 | Unused | 0 |
| 7 | User's first name | JOHN |
| 8 | User's last name | PUBLIC |
| 9 | Caller's location | OTTAWA, ON |
| 10 | ANSI mode (0=off, 1=on)| 1 |
| 11 | User's security level | 32000 |
| 12 | User's time left | 60 |
+----------------------------------------------------------+
Feel free to make any changes you wish to the door, and recompile
it! One of the best and most enjoyable ways to learn OpenDoors is
by experimenting. If you are a registered owner of OpenDoors, you
may even distribute your own versions of this door. Also, you may
find that EZVote serves as a good framework for building your own
doors.
The EZVote door behaves similarly to most other door programs,
and will have a fair bit in common with any other door you write
in OpenDoors. What you see in the output window is identical to
what a remote user will be seeing. If the user has ANSI or AVATAR
mode turned on, you will see the same colours as they do, and if
they have screen clearing turned on, your screen will be cleared
when their's is. The status line at the bottom of the screen will
list the name of the user currently on-line (if you are using the
sample DORINFO1.DEF file, the user's name will be "The Sysop"),
the user's location, and the user's baud rate (0 if the door is
operating in local mode). You will also be told how much time the
OpenDoors Door Toolkit Manual - Version 4.10 Page 25
user has left, and there will be indicators as to whether the
user has ANSI and/or AVATAR modes on, etc. If the user wishes to
Chat with the sysop (ie, they have paged the sysop, but haven't
receive a response yet), a [Want-Chat] indicator will be flashing
on the status line. Try Paging the sysop, using OpenDoors built
in sysop page feature. The following function keys will also be
available to the sysop in any OpenDoors door:
[UP]/[DOWN] - Use the arrow keys to increase or decrease the
amount of time which the user has left in the door.
[Alt]-[C] - Allows the sysop to break into chat with the user
at any time. [Alt]-[C] again, or [ESC] will end
chat mode. (Notice that the Want-Chat indicator
will also be turned off, if it was flashing. If
your door is running under Apex, RemoteAccess or
QuickBBS, paging from within the door will even
cause the Want-Chat indicator to stay lit when the
user returns to the BBS)
[Alt]-[J] - Allows the sysop to shell to DOS, if enough memory
is available. Simply type EXIT to return to the
door again.
[Alt]-[H] - Hang up on the user. When the sysop does this,
OpenDoors will optionally call a function you have
indicated in the OpenDoors control structure, to
allow you to close files, etc. OpenDoors will then
exit with the appropriate errorlevel:
0 - A critical error has occurred
1 - Carrier lost, user off-line
2 - Sysop terminated call, user off-line
3 - User time used up, user STILL ON-LINE
4 - Keyboard inactivity timeout, user
off-line
5-255 - Defined by your door
These errorlevel will allow sysops using your door
to optionally log the user back on-line, place the
BBS in "wait for call" mode, or whatever they wish,
depending on how the door exited
[Alt]-[L] - This key locks the user out of the BBS. It first
hangs up on the user, and then sets their security
level to 0, to prevent them from ever logging on
again. This feature may require use of the
EXITINFO.BBS file, depending on what system the
door is running under.
[Alt]-[K] - The "User Keyboard-Off" key allows the sysop to
temporarily prevent the user from typing anything
on their keyboard. This has no effect on the local
keyboard, but causes OpenDoors to ignore any
keystrokes from remote.
OpenDoors Door Toolkit Manual - Version 4.10 Page 26
[Alt]-[N] - The "Sysop Next" key, this function reserves the
system for use by the sysop after the user logs
off, if the door is running under an Apex or RA
1.00 or later system.
[Alt]-[D] - "Drop to BBS" key. This function allows the sysop
to exit the door and return the user to the BBS,
without hanging up.
[F1]..[F10] - The Function keys [F1] thru [F10] allows the sysop
access to various types of information on the
status line, or to turn the status line off. These
keys are as follows:
[F1] - Display basic door and user information
[F2] - Display phone numbers and important dates
[F3] - Display security flags and up/download info
[F4] - Display system information and current time
[F5] - Display message info and user's settings
[F6] - Display chat reason and sysop's comment
[F9] - Display help information for sysop
[F10] - Turn off the status line
Now, let us take a closer look at the actual source code for the
EZVote door. If you have not already printed out a copy of this
manual, and possibly the EZVOTE.C file as well, it would probably
be a good idea to do so now.
Notice that near the top of the program, along with all the
standard header files, the OPENDOOR.H file is included. This file
must be included in all programs written under OpenDoors. If you
are placing the OPENDOOR.H file in the same directory as the door
you are compiling, simply include the line:
#include "opendoor.h"
in your program. If you are placing the OPENDOOR.H in your
include directory, along with the rest of your header files, use
the line:
#include <opendoor.h>
You may notice the file structure just before the main function
in the EZVote door. EZVote stores its data file of questions,
results, and who has voted on what in a single fixed length file
called EZVOTE.BBS. This file is simply a memory image of the file
structure. The elements in this structure includes the total
number of questions, the total number of users that the door
knows about, the questions they have and have not voted on, the
actual questions and answers themselves, and so on. The execution
of the EZVote door begins with the allocation of memory for its
file structure.
OpenDoors Door Toolkit Manual - Version 4.10 Page 27
Next, the EZVote program calls the od_init_with_config()
function. This function instructs OpenDoors to begin execution,
by reading a configuration file if available, setting up some of
its internal storage, reading the door information file (eg.
DORINF1.DEF, DOOR.SYS), and begins communicating with the modem
(if it is not running in local mode). The od_init_with_config()
function is only required if you wish your door to use a
configuration file. In this case, od_init_with_config() must be
the first OpenDoors function you call. If you do not call the
od_init_with_config(), the OpenDoors initialization process will
ocurr whenever your program calls its first OpenDoors function.
For more information on configuration files in OpenDoors, please
see page .
The EZVote door also include the optional OpenDoors log file
system. To add log file capabilities to a door, the line
od_log_open() is simply placed after the od_init_with_config()
function. OpenDoors will now automatically include the logfile
system, and make the most common logfile entries, such as the
time the user enters and exits the door, sysop pages, shell to
DOS, and so on.
The next line in the main() function of the EZVote door looks as
follows:
od_control.od_before_exit=save_file;
This line simply tells OpenDoors to call the save_file() function
(to save the EZVOTE.BBS data file) before it exits. If you do not
wish OpenDoors to call any function before exiting, simply leave
this variable set to its default of NULL. Keep in mind that
OpenDoors automatically shuts down the door and returns control
to the BBS, if it detects that the user's time has expired, if
the user has hung up, and so on. As a result, it is possible that
OpenDoors could cause your program to exit at any time an
OpenDoors door driver is called. Hence, the use of this
od_control. od_before_exit variable will allow you to finish any
uncompleted activities, such as closing data files, before
control is returned to the BBS.
After EZVote has performed these door related startup procedures,
it opens/creates its EZVOTE.BBS data file. If the EZVOTE.BBS file
exists in the current directory, it is opened and read. If the
file does not exist, then EZVote creates a new one. Next, EZVote
searches through the data file for the name of the user who is
currently on-line. This allows EZVote to keep track of all the
users who have used it, with its own statistics about them.
EZVote also compares the name of the user currently on-line to
the name of the system's sysop. If they match, the EZVote will
also enable it's sysop-only functions, such as deleting questions
from the door.
Once EZVote has done all of this housekeeping, it begins to
communicate with the user. All of the functions performed by the
EZVote door center around the main menu, which is displayed by
the main_menu() function. The EZVote door is written in such a
OpenDoors Door Toolkit Manual - Version 4.10 Page 28
way that the main menu may be either the built-in menu, or one
contained in an external, sysop definable, ASCII/ANSI/AVATAR
file. Hence, the main_menu() function begins by attempting to
display a EZVOTE.ASC/ANS/AVT file, by use of the od_send_file()
function. If such a file is found, the od_send_file() function
will display the appropriate file corresponding to the current
graphics mode, and return a value of TRUE. (For more information
on TRUE/FALSE Boolean values, see the entry on "BOOLEAN VALUES",
in the glossary.) The EZVote main_menu() function then tests the
value returned by the od_send_file() function. If the
od_send_file() function was unable to find the appropriate file,
OpenDoors proceeds to display its built-in main menu. Before the
main menu is displayed, you will notice that the screen is
cleared (the od_clr_scr() function only clears the screen if the
user has screen clearing mode turned on), as well as the keyboard
input buffer. The keyboard buffer is cleared by the
od_clear_keybuffer() function, in order to prevent unwanted
behaviour, if the user has been pressing keys on their keyboard
while the door was loading, etc. While all the internal OpenDoors
functions check for ANSI/AVATAR mode, EZVote also checks the
status of the od_control.user_ansi variable. This allows it to
only display extended characters (such as the line and box
drawing characters) to users who have ANSI/AVATAR capabilities.
Menu display is accomplished using the od_disp_str() function.
Also note that when using the OpenDoors display functions you
must end a line with the "\n\r" sequence, instead of the single
"\n" that you would use with the C printf() function. In door
program, both the "\n" (line feed) and "\r" (carriage return)
characters must be sent to the modem, in order that the text is
displayed correctly on the remote user's screen.
The remainder of the EZVote door should be more or less self-
explanatory. To learn more about OpenDoors and door programming,
you should now continue to look through the following chapter,
which describes the functions that you can use when creating
doors with OpenDoors. You will probably also be interested in
looking at, compiling, testing and altering the other example
programs included in the OpenDoors package. There are also a
number of example programs throughout this manual, that will help
to demonstrate how you can accomplish various things using
OpenDoors.
OpenDoors Door Toolkit Manual - Version 4.10 Page 29
--------------------------------------------------------------------------------
CHAPTER 4 - THE OPENDOORS DOORDRIVER FUNCTIONS
--------------------------------------------------------------------------------
AN OVERVIEW OF THE FUNCTIONS
-------------------------------------------------------------------------------
All of the activities of an OpenDoors door program are
coordinated through one of two facilities - the door driver
functions, and the OpenDoors door control structure.
Any door program written with the OpenDoors door driver will have
to make use of the OpenDoors door driver functions for all of its
door-related input and output. The OpenDoors door driver
functions also provide many capabilities to your door programs,
such as displaying ASCII/ANSI/AVATAR files, controlling the
door's operation, and so on.
You should also note that much of the information about the user
who is online, information about the system your door is running
under, and variables to customize OpenDoors' behavior, are
accessed not through the door driver functions, but the OpenDoors
control structure. The control structure is described in the
section beginning on page 119.
Below, the door driver function available to door programs
written with OpenDoors are listed, grouped according to general
categories of functionality. On the following pages, the
OpenDoors functions and their use is described in detail, listed
in alphabetical order.
--------------------------------------------------------------------------------
OUTPUT DISPLAY FUNCTIONS
FUNCTIONS -----------------
od_disp_str() Displays a normal, NULL-terminated
string. (page 46)
od_disp() Sends the specified number of characters
to the modem, with or without local
echo. (page 44)
od_printf() Performs formatted output, as the
printf() function does. Also allows
imbedded codes to change display colour.
(page 93)
od_putch() Displays a single character. (page 97)
od_emulate() Displays a character, interpreting
imbedded ANSI/AVATAR codes. (page 62)
OpenDoors Door Toolkit Manual - Version 4.10 Page 30
od_repeat() Displays the same character any number
of times, using AVATAR optimization, if
possible. (page 99)
od_draw_box() Draws a window on the screen in
ANSI/AVATAR graphics mode. (page 48)
COLOUR FUNCTIONS
----------------
od_set_colour() Sets current colour to specified
foreground and background settings.
(page 108)
od_set_attrib() Sets current colour to specified IBM-PC
display attribute. (page 105)
SCREEN FUNCTIONS
----------------
od_clr_scr() Clears the screen, if user has screen
clearing enabled. (page 42)
od_clr_line() Clears the remainder of current line.
(page 40)
od_set_cursor() Sets the position of the cursor, if
ANSI/AVATAR mode is enabled. (page 111)
FILE DISPLAY FUNCTIONS
----------------------
od_send_file() Displays an ASCII/ANSI/AVATAR file (for
instance, an .ANS file created by a
program such as "TheDraw" (page 101)
od_hotkey_menu() Displays an ASCII/ANSI/AVATAR menu file,
with hotkeys active. (page 71)
od_list_files() Lists the files available for download
in an area, using a FILES.BBS file.
(page 87)
--------------------------------------------------------------------------------
INPUT od_get_answer() Inputs a single key from the keyboard,
FUNCTIONS allowing only particular responses.
(page 66)
od_get_key() Inputs a single key from the keyboard,
optionally waitin if a key is not
available. (page 67)
od_input_str() Inputs a string of specified length,
from the keyboard. (page 83)
od_edit_str() Formatted string editing function,
requiring ANSI/AVATAR graphics. (page
51)
OpenDoors Door Toolkit Manual - Version 4.10 Page 31
od_clear_keybuffer() Removes any waiting keys from the
keyboard input queue. (page 38)
--------------------------------------------------------------------------------
DOOR od_init() Begins door operation by setting up
FUNCTIONS the OpenDoors control structure, setting
up the local screen, initializing the
FOSSIL driver (if applicable), and
reading the door information file. (page
73)
od_exit() Ends door operations, closing the FOSSIL
driver, re-writing the door information
file, and optionally returning control
to the BBS. (page 64)
od_kernal() The central OpenDoors control function,
which should be executed every few
seconds. (page 85)
od_set_statusline() Temporarily alters the setting of the
current OpenDoors status line. (page
113)
od_page() Allows the user to page the sysop for
chat. (page 92)
od_spawn() OpenDoors quick-spawn function. Executes
an external program (eg. file
compressor, external protocol, etc.) on
a separate screen, restoring the
OpenDoors screen afterwards. (page 115)
od_spawnvpe() OpenDoors full-featured spawn function.
Executes an external program on a
seperate screen, searching the path for
tthe program, allowing you to specify an
environment to pass to the child
process, and returning the errorlevel
returned by the chiold process. (page
117)
od_carrier() Allows detection of carrier signal in
programs that have disabled OpenDoors
internal checking. (page 34)
--------------------------------------------------------------------------------
CONFIG od_init_with_config() Begins doors operations, parsing
FILE information from a configuration file.
FUNCTIONS (page 76)
od_colour_config() Transfers a colour configuration line to
a colour attribute value. (page 36)
OpenDoors Door Toolkit Manual - Version 4.10 Page 32
--------------------------------------------------------------------------------
LOGFILE od_log_open() Opens a log file and begins logging
FUNCTIONS activities. (page 89)
od_log_write() Creates a log file entry. (page 91)
OpenDoors Door Toolkit Manual - Version 4.10 Page 33
OD_CARRIER()
--------------------------------------------------------------------------------
PURPOSE To determine the status of the carrier detect signal, in programs
where OpenDoors' internal carrier detection has been disabled.
FORMAT int od_carrier(void);
RETURNS TRUE if a carrier is present, or
FALSE if no carrier is present, or in local mode.
DESCRIPTION Usually, you will not have any use for the od_carrier() function,
as OpenDoors automatically monitor's the carrier detect signal,
and will correctly recover if the carrier detect signal is lost
while the door is operating in remote mode. However, in some
programs, you may wish to disable OpenDoors' internal carrier
detection routines, using the od_control.od_disable variable. Two
such cases in which you might want to do this, are a call-back
verification door, which disconnects the user and attempts to
call them back, or in a terminal program, which is in fact not a
door at all (and as such you would not want to have OpenDoors
exit when the carrier detect signal is lost). In cases like
these, you will then be able to use the od_carrier() function in
order to determine the state of the carrier detect signal.
This function will return a Boolean value (for more information
on Boolean values, see the Glossary which begins on page 192), of
either TRUE or FALSE. If a carrier detect signal is present when
the function is called, it will return TRUE, and if no carrier
detect signal is detected, it will return FALSE. Since there is
no remote connection, and thus no carrier when OpenDoors is
operating in local mode, this function will always return a value
of FALSE in local mode.
EXAMPLE As an example of the use of this function, let us consider a call
back verification door, which hangs up on the user, and then
calls the user back at their entered phone number, in order to
verify the correctness of that number. This program would
probably contain a function that is responsible for disconnecting
the user, waiting for the connection to be broken, and then
phoning the user. At some point in this function, likely just
prior to the point where the function hangs up on the user, you
would disable OpenDoors' internal carrier detection, using the
line:
od_control.od_disable |= DIS_CARRIERDETECT;
OpenDoors Door Toolkit Manual - Version 4.10 Page 34
You would then want to have a piece of code which would simply
wait up to a given amount of time for the carrier signal to drop.
If this occurs, you would continue to place the call, and if it
does not occur, you would probably try your hangup procedure one
or two more times. In this example, the function will simply
return with a value of FALSE if the carrier signal does not drop,
and will call the place_call() function if it does drop,
returning the Boolean value returned by the place_call()
function. Our piece of example code would be as follows:
char hangup(void)
{
register long timer;
... /* Perform hangup */
/* Wait up to 30secs (546 ticks) */
timer=(*(long far *)0x46cL)+546L;
while(timer>=*(long far *))
{ /* If carrier has been lost, dial the modem */
if(!od_carrier()) return(place_call());
}
return(FALSE);
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 35
OD_COLOUR_CONFIG()
--------------------------------------------------------------------------------
PURPOSE Parses a colour configuration line from the configuration file,
generating a colour attribute value.
FORMAT unsigned char od_colour_config(char *config_line);
RETURNS Colour attribute value
DESCRIPTION This function will be of use if you are using the configuration
file system of OpenDoors, and wish to allow the sysop to specify
text colours to be used in your door. While OpenDoors
automatically recognizes colour configuration settings for things
such as sysop chat mode and FILES.BBS listings, you may wish to
add additional colour configuration options. In this case, you
could call the od_colour_config() function from your custom line
function. For more information on the custom line function, see
the description of the od_init_with_config() function.
To use this function, simply pass the configuration file line you
wish to have parsed to the function in it's single parameter. The
function will then return a colour attribute value in the same
format that is used but the od_set_attrib() function. Colours are
specified using a string of the format:
{Flashing} {Bright} [foregoround] on [background]
Where "Flashing" is an optional keyword indicating that the text
should be flashing. "Bright" is an optional keyword indicating
that the foreground colour should be bright. Foreground is the
name of a foreground colour, and background is the name of a
background colour. Case (upper or lower) is not significant.
The colour keywords are language configurable, using the global
array od_config_colours. The default definition of this array is
listed below. Note that all keywords must all be uppercase. The
first eight elements in this array are the names of the eight
basic colours, in order from 0 to 7. The next two options are
alternative names for the colours 6 and 7. This is provided
because these two colours look significantly different in low and
high intensity, and will often be called by different names. The
last to elements in this array are the "Bright" and "Flashing"
keywords.
char od_config_colours[12][33]={
"BLACK",
"BLUE",
"GREEN",
"CYAN",
"RED",
"MAGENTA",
"YELLOW",
OpenDoors Door Toolkit Manual - Version 4.10 Page 36
"WHITE",
"BROWN",
"GREY",
"BRIGHT",
"FLASHING"};
SEE ALSO od_init_with_config()
EXAMPLE See the example accompanying the od_init_with_config() function
documentation.
OpenDoors Door Toolkit Manual - Version 4.10 Page 37
OD_CLEAR_KEYBUFFER()
--------------------------------------------------------------------------------
PURPOSE Function to clear the input keyboard buffer
FORMAT void od_clear_keybuffer(void);
RETURNS N/A
DESCRIPTION OpenDoors maintains its own keyboard input buffer, in order to
permit the user to "type ahead" - to send input to the door prior
to the time when it is ready to process those key presses. For
example, the user could begin to type a command while a menu is
still being displayed, and when your door reaches the point of
inputting the menu command, the characters already typed by the
user will already be waiting for the OpenDoors input functions.
Note that the keyboard input buffer will include both the keys
hit by the user on-line, and the non-function keys (ie, Alt-C
will not appear in the OpenDoors keyboard buffer), hit by the
sysop. This allows both the user on-line and the sysop to control
the door at any time. If the sysop wishes to temporarily prevent
the user from having any control over the door, the sysop may use
the Alt-K (user-keyboard off) key. The key strokes placed in the
OpenDoors type-ahead buffer will be retrieved by the od_get_key()
and od_input_str() functions. The keyboard buffer can contain a
maximum of 64 user keystrokes in this version of OpenDoors, after
which any additional keystrokes will simply be discarded by
OpenDoors.
There are times, however, when you will want to erase any keys
that have been hit by the user, to prevent them from typing
ahead. For example, if your door has been busy doing some
processing for a few moments, they user may have been pressing
keys on their keyboard - perhaps in the hope that doing so will
speed things up. These keys will be waiting in the type-ahead
buffer, and if one of the keys the user entered was a valid
response to the next prompt in your door, the user may find that
they have accidentally made a choice they did not wish to. A well
designed door will simply erase the contents of the type-ahead
buffer after any long period of internal processing, etc. Keep in
mind that too much use of the od_clear_keybuffer() function can
be just as undesirable as not using it all, as there are times
when the presence of the keyboard buffer can prove to be very
useful for the user of a door.
To erase the contents of the type-ahead buffer, you simply call
the od_clear_keybuffer() function. This function takes no
parameters, and does not return any value.
OpenDoors Door Toolkit Manual - Version 4.10 Page 38
SEE ALSO od_get_key(), od_input_str(), od_edit_str()
EXAMPLE For one example of the use of the od_clear_keybuffer() function,
see the example door program EZVote, which is described beginning
on page 25. Below is another example of using this function. In
this case, we present a simple function, wait_for_return(), which
simply pauses for the user to press their [Enter]/[Return] key.
The function begins by displaying a prompt asking for the [Enter]
or [Return] key to be pressed. The function then clears the
keyboard input buffer, and waits until the user presses the
carriage return key, using the od_get_key() function. Note also
that this function will only continue if the user has pressed the
correct key. This is a good idea in all door programs, as it
allows your door to distinguish between a character pressed by
the user, and a "line noise" character.
void wait_for_return(void)
{ /* Display prompt */
od_disp_str("Please Press [Enter] to continue...\n\r");
od_clear_keybuffer(); /* Clear keyboard buffer */
while(od_get_key(TRUE)!=13); /* Wait for Enter key */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 39
OD_CLR_LINE()
--------------------------------------------------------------------------------
PURPOSE Clears the rest of the current display line
FORMAT void od_clr_line(void);
RETURNS N/A
DESCRIPTION This function clears the line that the cursor is on, from the
cursor position to the end of the line. After the rest of the
line is cleared, the cursor is automatically returned to the
position it was at prior to issuing the command. Hence, if the
display line the cursor was located on looked as follows, with
the underscore (_) character representing the cursor position:
This is a_line of text!
With the cursor between the words "a" and "line", after the
od_clr_line command is issued, the line would appear as follows:
This is a_
With the cursor directly following the word "a". Note that this
function places a space character at the cursor location, and
every location up to the end of the line.
When the door is running in plain ASCII mode, this command will
simply clear the rest of the line by manually sending a series of
space and backspace characters. When ANSI or AVATAR modes are
active, the corresponding ANSI/AVATAR control sequence will be
sent in order to accomplish the line clear. Since the graphics
mode sequences are much shorter than the sequence that would be
required to clear the line manually, the use of this function
will cause your door's graphics to display much more quickly when
ANSI or AVATAR modes are active. Also note that in ANSI or AVATAR
graphics modes, the line will be cleared with the currently
selected colour attribute. Thus, if you wanted to place a blue
background on a particular line, you would use the
od_set_colour() (or od_set_attrib()) function, then use the
od_set_cursor() function to locate the cursor at the beginning of
the desired line, followed by the od_clr_line() function. Just
such a procedure is demonstrated in the example, below.
SEE ALSO od_clr_scr(), od_set_cursor()
OpenDoors Door Toolkit Manual - Version 4.10 Page 40
EXAMPLE Below, is an example of a function that clears an entire line
with a specified colour. Since this function performs operations
that require ANSI or AVATAR graphics mode, it should only be used
in a case where these modes are known to be available. For
example, this function would be useful in a full-screen editor or
viewer, or when performing ANSI animations. The function accepts
three parameters: the line to be cleared (where 1 is the first
line, 2 the second, and so on), the foreground colour of this
line, and the background colour of this line.
This function differs from the od_clr_line() function itself in
several important manners. First of all, this function clears the
entire line, whereas the od_clr_line() function can be used to
clear only the remaining characters of the line, after any
particular location. Also, as mentioned before, this function
selects a colour to clear the line to, and moves the cursor to
the line which is to be cleared - neither of which is done by the
od_clr_line() function.
void clear_line(char line_number,char foreground,char background)
{
od_set_cursor(line_number,1); /* move to correct line */
od_set_colour(foreground,background); /* set colour */
od_clr_line(); /* clear entire line */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 41
OD_CLR_SCR()
-------------------------------------------------------------------------------
PURPOSE The OpenDoors clear screen function
FORMAT void od_clr_scr(void);
RETURNS N/A
DESCRIPTION The od_clr_scr() function can be used to clear the door screen.
(ie, the user's screen and local screen with the exception of the
status line are cleared.) Also, if your door is running under a
system, such as RemoteAccess, Apex or QuickBBS, which produce an
EXITINFO.BBS file, this function will detect the user's screen
clearing setting, and only clear the screen if screen clearing is
turned on. If an EXITINFO.BBS file is not available, this
function will always clear the screen (as OpenDoors will not be
able to determine whether or not the user has screen clearing
enabled). If your door will be running under BBS systems that do
not pass the user's screen clearing setting to the door, you may
wish to determine yourself whether or not the user's system
supports screen clearing codes, during the first time the user
uses the door. You will then be able to store this setting in a
data file. The example below demonstrates how to detect whether
or not the user's system supports screen clearing.
You should note that the ability for the user's terminal to
support screen clearing codes is independent of the user's ANSI /
AVATAR graphics mode settings. The od_clr_scr() function
accomplishes screen clearing by sending an ASCII 12 character to
the remote terminal, and thus ANSI or AVATAR graphics are not
necessarily required in order to clear the screen.
For more information on the user's screen clearing setting,
please refer to the user_attrib variable in the OpenDoors Control
Structure chapter of this manual. If you wish to force a screen
clear, regardless of the user's screen clearing setting, simply
use the function call:
od_emulate(12);
SEE ALSO od_clr_line()
EXAMPLE Below is an example of a function which determines whether or not
the user's system supports screen clearing. This function will
return a value of TRUE if screen clearing is supported, and will
return a value of FALSE if screen clearing is not supported:
OpenDoors Door Toolkit Manual - Version 4.10 Page 42
int user_supports_screen_clearing(void)
{
char answer;
/* display instructions to user */
od_disp_str("In order for this door to function\n\r");
od_disp_str("correctly, we must know whether or not\n\r");
od_disp_str("your system supports screen clearing.\n\r");
od_disp_str("In a moment, we will attempt to clear\n\r");
od_disp_str("your screen in order to test your system's\n\r");
od_disp_str("capabilities.\n\r\n\r");
od_disp_str("Please press [Enter]/[Return] when you are\n\r");
od_disp_str("Ready to perform this test.\n\r");
while(od_get_key(TRUE)!=13); /* wait for [Return] key */
od_clr_scr(); /* attempt to clear screen */
/* ask user if their screen cleared */
od_disp_str("Did your screen just clear? (Y/N)\n\r");
for(;;) /* loop until user chooses [Y]es or [N]o */
{
answer=od_get_key(TRUE); /* Get user's answer */
if(answer=='y' || answer=='Y') return(TRUE);
if(answer=='n' || answer=='N') return(FALSE);
}
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 43
OD_DISP()
-------------------------------------------------------------------------------
PURPOSE Sends a buffer of text with optional local echo
FORMAT void od_disp(char *buffer, int size, char local_echo);
RETURNS N/A
DESCRIPTION This function allows you to send a buffer of text of any
specified length, with the option of enabling or disabling local
echo. You will probably have little use for this function -
instead you will most likely display strings using either the
od_disp_str() or od_printf() functions, depending on whether or
not you wish to use printf()'s formatting options. For a
breakdown of the uses of the various OpenDoors display functions,
see the description of the od_disp_str() function, on page 46.
There are two cases when this function will come in useful:
1.) If you wish to display a buffer of characters of known
length, which may contain null (ASCII 0) characters.
Since this character is used by the C language to
indicate the end of a string, the other two string
display functions (od_disp_str() and od_printf()) will
not send this character to the remote system.
2.) If you wish to send text to the remote system without
having it displayed on the local screen, or if you wish
to send strings to the modem when it is in command mode,
without having these characters displayed on the local
screen.
The od_disp() function is called with three parameters. The first
parameter, *buffer, is a pointer to a buffer of characters you
wish to have displayed. The second parameter, size, is simply the
number of characters in the buffer to be displayed. If the third
parameter, local_echo, is set to TRUE, then all characters sent
to the modem will also be displayed on the local screen. If the
third parameter is set to FALSE, then the buffer will be sent to
the modem without being echoed to the sysop's screen.
SEE ALSO od_disp_str(), od_printf(), od_putch(), od_repeat(), od_emulate()
EXAMPLES The following are a few examples of the use of the od_disp()
function:
OpenDoors Door Toolkit Manual - Version 4.10 Page 44
In order to display a single character, contained in the variable
"character", without echo to the local screen:
od_disp(&character,1,FALSE);
In order to send a command to the modem (only if you know that
the modem is in command mode), with the command contained in the
null-terminated string "string":
od_disp(string,strlen(string),FALSE);
In order to send exactly 5 characters from the buffer "buffer",
WITH echo to the local screen:
od_disp(buffer,5,TRUE);
OpenDoors Door Toolkit Manual - Version 4.10 Page 45
OD_DISP_STR()
--------------------------------------------------------------------------------
PURPOSE Displays a string to the screen (remote and local)
FORMAT void od_disp_str(char *string);
RETURNS N/A
DESCRIPTION The two functions most often used for displaying strings within a
door are the od_disp_str() and od_printf() functions. The
od_printf() function allows for formatted output, whereas the
od_disp_str function simply displays the actual contents of the
string passed to it. If you wish to display a single character,
use the od_putch() function. If you wish to send a string or
buffer to the modem without local echo, use the od_disp()
function. If you wish to send a sequence of the same character to
the modem, the od_repeat() function will use graphics control
codes, if available to display the sequence much faster than
simply sending the same character in repetition. Also, if you
wish to send ANSI or AVATAR graphics control codes, and have them
emulated on the local screen, use the od_emulate() function.
The od_disp_str() function displays the contents of the null-
terminated string pointed to by *string. Display is sent to both
the local screen and modem (presuming the door is not running in
local mode).
All modem output is accomplished through the Fossil driver. Also,
if the variable directvideo is set to 1, then the screen display
is accomplished by direct writes, either to video memory, or to
the DesqView screen buffer, if DesqView is running. If
directvideo is set to 0, then BIOS function calls are used for
video output. While using direct video writes results in much
greater screen updates speeds, it will also cause difficulties
for people running in multitaskers, such as DesqView. Ideally,
you could design your door to either accept a command-line
parameter or a setting in it's configuration file to allow the
sysop using your door to select either direct or BIOS writes.
An important thing to keep in mind when using the od_disp_str()
function, is that you should use "/n/r" instead of simply "/n"
for a new line. This is due to the fact that terminal programs
usually require a carriage-return line-feed sequence (/n/r),
instead of just a line-feed (/n). For example, instead of using:
od_disp_str("Hello world!\n");
You should use:
OpenDoors Door Toolkit Manual - Version 4.10 Page 46
od_disp_str("Hello world!\n\r");
To change the cursor colour or location of output with the
od_disp_str() function, refer to the od_set_cursor() and the
od_set_attrib() functions.
SEE ALSO od_disp(), od_printf(), od_putch(), od_repeat(), od_emulate()
EXAMPLES Below are a few examples of various uses of the od_disp_str()
function:
Displaying three string constants on separate lines:
od_disp_str("This is an example\n\r");
od_disp_str("of the OpenDoors\n\r");
od_disp_str("od_disp_str() function\n\r");
Displaying three string constants on the same line:
od_disp_str("Another ");
od_disp_str("od_disp_str() ");
od_disp_str("example\n\r");
Displaying a string variable:
char string[80];
strcpy(string,"This is a string!\n\r");
od_disp_str(string);
OpenDoors Door Toolkit Manual - Version 4.10 Page 47
OD_DRAW_BOX()
--------------------------------------------------------------------------------
PURPOSE Draws a window on the screen in ANSI or AVATAR graphics modes.
FORMAT int od_draw_box(char left, char top, char right, char bottom);
RETURNS TRUE on success, FALSE on failure
DESCRIPTION This function is for use in ANSI or AVATAR graphics modes. This
function will draw a window in the current display attribute, at
the specified location on the screen. The boarder of the window
is made up of the characters specified in the od_control.
od_box_chars[] array. If AVATAR graphics mode is available, this
function uses AVATAR control codes to display the window in less
than 1/10 the length of time required to display the window in
ANSI mode.
The first two parameters of this function, "left" and "top",
specify the coordinates of the top, left-hand corner of the
window to be draw. The third and fourth parameters, "right" and
"bottom", specify the coordinates of the bottom, left-hand corner
of the window. Like the values passed to the od_set_cursor()
function, these coordinates are relative to the upper left-hand
corner of the screen, with the position (1,1) being this corner.
As mentioned above, this function will display the window in the
current text colour. Thus, before calling this function, you
should use either the od_set_colour() or the od_set_attrib()
function to specify the colour in which you would like to have
the window displayed.
Normally, the boarder of the window will be displayed using the
IBM extended ASCII characters which produce a single line
boarder. However, you may wish to have the boarder displayed
using different characters. In this case, the characters used to
display the boarder can be specified by the od_control.
od_box_chars variable, described in the OpenDoors control
structure section of this manual.
SEE ALSO od_set_colour(), od_set_attrib(), od_clr_scr(), od_edit_str(),
od_set_cursor()
EXAMPLE As an example of the use of the od_draw_box() function in
conjunction with the od_edit_str() function, we show a portion of
a program which displays a window, and allows the user to input
the name of a file they would like to upload, a description of
the file, and whether they want it to be a private upload. The
OpenDoors Door Toolkit Manual - Version 4.10 Page 48
user is able to move among fields using the tab key, and select a
"continue" button when they are finished. The function returns
TRUE if the user selects continue, and FALSE if the user presses
[ESCape].
// Main "dialog box" function
int get_information(char *filename, char *description,
char *private)
{
char current_field=1; // Currently selected field
int choice; // User's choice
od_set_colour(L_WHITE,D_BLUE); // Display window
od_draw_box(10,5,70,13);
od_set_cursor(5,25); // Display window title
od_set_colour(L_GREEN,D_BLUE);
od_disp_str(" ENTER FILENAME INFORMATION ");
od_set_colour(L_CYAN,D_BLUE); // Display fields and titles
od_set_cursor(6,15);
od_disp_str("FILENAME : ");
od_repeat(176,13);
od_set_cursor(7,12);
od_disp_str("DESCRIPTION : ");
od_repeat(176,43);
od_set_cursor(8,16);
od_disp_str("PRIVATE : ");
od_repeat(176,2);
draw_button();
filename[0]='\0'; // Blank out contents of input variables
description[0]='\0';
private[0]='\0';
for(;;) // Main dialog box loop
{
if(current_field==4) // If field is the button
{
od_set_colour(L_GREEN,D_BLUE); // Highlight button
draw_button();
do // Loop until user presses [TAB], [ENTER], or [ESC]
{
choice=od_get_key(TRUE);
} while(choice!=9 && choice!=13 && choice!=27);
od_set_colour(L_CYAN,D_BLUE); // Un-highlight button
draw_button();
if(choice==13) return(TRUE); // If [ENTER] was pressed
if(choice==27) return(FALSE); // If [ESC] was pressed
current_field=1; // Otherwise, [TAB] was pressed
}
switch(current_field) // According to selected field
OpenDoors Door Toolkit Manual - Version 4.10 Page 49
{ // Input from the appropriate line
case 1:
choice=od_edit_str(filename,"FFFFFFFFFFFF",6,26,
0x1b,0x1a,176,
EDIT_FLAG_EDIT_STRING|
EDIT_FLAG_ALLOW_CANCEL|
EDIT_FLAG_FIELD_MODE|
EDIT_FLAG_KEEP_BLANK);
break;
case 2:
choice=od_edit_str(description,"*******************",
7,26,0x1b,0x1a,176,
EDIT_FLAG_EDIT_STRING|
EDIT_FLAG_ALLOW_CANCEL|
EDIT_FLAG_FIELD_MODE|
EDIT_FLAG_KEEP_BLANK);
break;
case 3:
choice=od_edit_str(private,"Y",8,26,
0x1b,0x1a,176,
EDIT_FLAG_EDIT_STRING|
EDIT_FLAG_ALLOW_CANCEL|
EDIT_FLAG_FIELD_MODE);
}
// If user pressed [ESCape]
if(choice==EDIT_RETURN_CANCEL) return(FALSE);
// If user choice to go to previous field
if(choice==EDIT_RETURN_PREVIOUS)
{
if(current_field==1) // If at first field
{
current_field=4; // Go to last field
}
else // If not at first field
{
--current_field; // Go to previous field
}
}
else // If user chose next field
{
++current_field; // Go to next field
}
}
}
void draw_button(void) // Function to display the button
{
od_draw_box(12,10,23,12); // Draw box for button
od_set_cursor(11,14);
od_disp_str("Continue"); // Display text in button
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 50
OD_EDIT_STR()
--------------------------------------------------------------------------------
PURPOSE Allows you to perform formatted input with full line editing
features, etc., in ANSI / AVATAR graphics mode.
FORMAT unsigned int od_edit_str(char *input_string, char *format_string,
int row, int col, unsigned char normal_colour, unsigned char
highlight_colour, char character, unsigned int flags);
RETURNS This function will return one of the following values. Note that
some of these values will only be applicable in certain cases.
For example, EDIT_RETURN_CANCEL will never be returned if you
have not enabled the cancel feature of this function.
EDIT_RETURN_ERROR Indicates that an error has occurred,
and the edit function was unable to run.
This will occur if there is an error in
one of the parameters, or if ANSI /
AVATAR graphics is not available
EDIT_RETURN_CANCEL Indicates that the user pressed the
cancel key [ESC], and that the string
was left unaltered.
EDIT_RETURN_ACCEPT Indicates that the user pressed the
accept key [Enter], or that the auto-
enter feature was activated.
EDIT_RETURN_PREVIOUS Indicates that the user wishes to move
to the previous field, by pressing [UP
ARROW], [SHIFT]-[TAB], etc.
EDIT_RETURN_NEXT Indicates that the user wishes to move
to the next field, by pressing [DOWN
ARROW], [TAB], etc.
DESCRIPTION To perform string input within OpenDoors, one of two functions
can be used, od_input_str() and od_edit_str(). The first
function, od_input_str(), allows simple line input and editing,
and can be used in ASCII, ANSI and AVATAR modes. The second
function, od_edit_str(), allows many formatted input options,
advanced line editing, and other features, but requires the use
of ANSI or AVATAR graphics modes.
The od_edit_str() function provides a great deal of features and
functionality, and as such, may appear to be one of the most
complicated functions within the OpenDoors door driver. The
simple fact that the function accepts eight parameters may make
OpenDoors Door Toolkit Manual - Version 4.10 Page 51
the od_edit_str() function seem daunting. However, you need not
concern yourself with all of the features available from the
od_edit_str() function in order to make use of it. Reading
through this section should give you some idea of what is
possible with the od_edit_str() function, and the following
examples should help to demonstrate the use of this function.
The first thing to remember about the od_edit_str() function is
that it requires ANSI / AVATAR graphics, as the graphics control
codes are needed for the advanced editing capabilities provided
by the od_edit_str() function. Thus, you will only want to use
the od_edit_str() in one of two cases; either in a door which
requires ANSI / AVATAR graphics to operate, or in the case that
you program tests for the availability of ANSI / AVATAR graphics,
and only calls od_edit_str() if graphics is available. If ANSI /
AVATAR graphics is not available, your program should use the
od_input_str() function instead.
As mentioned above, the od_edit_str() function allows for
advanced line editing, such as inputting and deleting text from
the middle of the string (whereas the od_input_str() function
only allows editing from the end of the string, such as
backspacing to erase a mistake). The edit functions available
from the od_edit_str() are listed below. Note that some of these
functions may or may not be available, depending upon the
capabilities of the user's terminal program. While there is no
single standard used for the transmission of special edit keys
such as the arrow keys, the od_edit_str() function makes as much
effort as possible to make all of the edit features available to
most terminal programs. Many of the edit functions can be
accesses using either [CONTROL]-key combinations or special keys
such as the arrow keys, delete key, and so on. OpenDoors will
recognize most of these special control keys when sent as either
an ANSI control sequence (which is sent by most terminal
programs), or as a DoorWay style scan code / ASCII code sequence
(which is also available from many terminal programs, but is not
usually required). The od_edit_str() edit functions are as
follows. Note that all edit functions are always available from
the local keyboard.
HOME - Moves the cursor to the beginning of the line being
edited. Press the [HOME] key, either in DoorWay mode or
from the local keyboard.
END - Moves the cursor to the end of the line being edited. Press
the [END] key, either in DoorWay mode or from the local
keyboard.
DELETE CHARACTER - Deletes the character under the cursor. Press
[DELete] on the local keyboard, in DoorWay mode, and
under many terminal programs without DoorWay mode.
Alternatively, press [CONTROL]-[G].
BACKSPACE - Deletes the character left of the cursor. Press
[BACKSPACE] or [CONTROL]-[H].
OpenDoors Door Toolkit Manual - Version 4.10 Page 52
TOGGLE INSERT MODE - Switches the od_edit_str() function between
insert mode and overwrite mode. Press [INSert], either
in DoorWay mode, or from the local keyboard.
Alternatively, press [CONTROL]-[V].
CURSOR LEFT - Moves the cursor left one character. Press [LEFT
ARROW] on the local keyboard, in DoorWay mode, and
under many terminal programs without DoorWay mode.
Alternatively, press [CONTROL]-[S].
CURSOR RIGHT - Moves the cursor right one character. Press [RIGHT
ARROW] on the local keyboard, in DoorWay mode, and
under many terminal programs without DoorWay mode.
Alternatively, press [CONTROL]-[D].
ERASE ENTIRE LINE - Press [CONTROL]-[Y].
ACCEPT INPUT - Press the [ENTER] / [RETURN] line to accept the
input. Alternatively, press [CONTROL]-[Z]. Note that
this key will only work when the current input is
"valid" (ie, it conforms to the format string, which is
described below)
CANCEL INPUT - Only available if specifically enabled on the
od_edit_str() command line. Press [ESCape].
NEXT FIELD - If enabled, allows the user to move to the next
field in a dialog box / form. Press [DOWN ARROW] in
DoorWay mode and under many terminal programs without
DoorWay mode. Alternatively, press [TAB]. Note that the
[DOWN ARROW] key is NOT usually available from the
local keyboard, as it is usually used to adjust the
user's remaining time.
PREVIOUS FIELD - If enabled, allows the user to move to the
previous field in a dialog box / form. Press [UP ARROW]
in DoorWay mode and under many terminal programs
without DoorWay mode. Alternatively, press [SHIFT]-
[TAB] on the local keyboard or in DoorWay mode. Again,
note that the [UP ARROW] key is NOT usually available
from the local keyboard, as it is usually used to
adjust the user's remaining time.
Let us now look at the parameters which the od_edit_str()
function accepts. The first parameter, input_string, is a pointer
to the string where the user's input should be stored. It is
important that this string be long enough to accommodate the
longest input your format string will permit, including the '\0'
C string terminator (ie, the string should be one character
greater than the length of the format string, not including the
format string's ' and " characters).
The second parameter, format_string, is a pointer to a string
which specifies the format and maximum length of the input the
od_edit_str() function should accept. Using the format string,
OpenDoors Door Toolkit Manual - Version 4.10 Page 53
not only do you specify the length of the input field, but you
can also force the user's input into certain formats. For
example, if you wished to input a North American style phone
number, you could use a format string of "###-###-####". Then
regardless of whether the user typed any dash character or not,
their input would be converted, as they type, to the format of
the phone number 613-526-4466. You could also specify a format
string such of "MMMMMMMMMMMMMMMMMMMMMMMMMMMMMM", which would
permit the user to enter a name of up to 30 characters. The
od_edit_str() function would then automatically capitalize the
name, so that the first character of each word is capitalized,
and the remain characters of the word is in lower case. Even if
the user were to move the cursor to the middle of the string they
had entered, and add or delete a space (and thus either make one
work two or two words one), od_edit_str() would re-format the
string to reflect the change. The valid characters for the format
sting, along with their meanings, are listed below. Note that the
format string is NOT case sensitive (except for literal strings
delimited by the '' or "" characters), and space characters can
be added at any point to increase legibility.
(Note that this string format is a modified version of a format
suggested in the OPENDOORS EchoMail conference, and it is
understood that a similar format is used by at least one other C
programming library. In using a similar format, it is not my
intention to copy someone else's idea, but simply to build upon a
format that it seems is familiar to some C programmers already.)
# Indicates that numeric characters from '0' to '9' are valid
for this position
% Indicates that numeric characters from '0' to '9', and the
space character (' ') are valid for this position.
9 Indicates that numeric characters from '0' to '9', along
with '.', '-' and '+' are valid for this position. This
format style is intended for floating-point numeric input.
? Indicates that any character is valid for this position.
* Indicates that any printable character, from ASCII 32 to
ASCII 127, is valid for this position.
A Indicates that alphabetical characters 'A' to 'Z', 'a' to
'z' and space (' ') are valid for this position.
C Indicates that city name characters are valid for this
position. As with the 'M' format character, words are
automatically capitalized so that the first letter is in
upper case, and all subsequent letters are in lower case. In
addition to permitting alphabetical characters and the space
(' ') character, the ',' and '.' characters are also
accepted in this position.
D Indicates that date characters '0' to '9', '-' and '/' are
valid for this position.
OpenDoors Door Toolkit Manual - Version 4.10 Page 54
F Indicates that MS-DOS filename characters are valid for this
position.
H Indicates that hexidecimal character '0' to '9', 'A' to 'F'
and 'a' to 'f' are valid for this position.
L Indicates that only lower case alphabetical characters 'a'
to 'z', and the space (' ') character is valid for this
position. However, if the user attempts to enter an upper
case alphabetical character in this position, it will
automatically be converted to the lower case equivalent.
M Indicates that name characters are valid for this position.
These characters are the alphabetical characters 'A' to 'Z',
'a' to 'z', and the space character (' '). A character's
case is converted such that the first character of a word is
in upper case, and all other letters are in lower case.
T Indicates that telephone number character '0' to '9', '(',
')', '-' and ' ' are valid for this position.
U Indicates that only upper case alphabetical characters 'A'
to 'Z', and the space (' ') character is valid for this
position. However, if the user attempts to enter a lower
case alphabetical character in this position, it will
automatically be converted to the upper case equivalent.
W Indicates that MS-DOS filename characters are permitted in
this position, including the '*' and '?' wildcard
characters.
X Indicates that alphanumeric characters 'A' to 'Z', 'a' to
'z', '0' to '9' and ' ' are valid for this position.
Y Indicates that yes/no characters 'Y', 'N', 'y', 'n' are
valid for this position. The characters are automatically
converted to upper case.
'/" Single or double quotes can be used to specify sequences of
characters that should appear at the same location in the
input string (referred to elsewhere as "literal strings").
When the user is entering the string, these characters are
automatically supplied, and the user is not required to type
them. Literal strings must begin and end with the same quote
character. Remember that the double quote (") character must
be imbedded in C strings by preceding the quote character
with a \ (backslash) character.
The third and fourth parameters, row and col specify the location
on the screen where the first (left most) character of the input
field should be located. These parameters are identical to the
row and col parameters passed to the od_set_cursor() function. In
other words, row specifies the line number on the screen, where 1
is the first line, and col specifies the column across the
screen, where 1 is the first column.
OpenDoors Door Toolkit Manual - Version 4.10 Page 55
The fifth and sixth parameters, normal_colour and
highlight_colour, allow you to specify the colour of the input
field. The fifth parameter, normal_colour, specifies the colour
of the input field when input is not taking place and the sixth
parameter, highlight_colour, specifies the colour of the field
while input is taking place. Thus, if you had several input
fields on the screen at one time, you would be able to make is
easier for the user to identify the currently active field by
having the field currently accepting input highlighted in a
colour distinct from the other fields. When the od_edit_str()
function begins, it will change the current colour of the field
from the normal colour to the highlighted colour. Then, when the
od_edit_str() function exits, it will change the current colour
of the field back to its normal colour. If you do not wish to
have the field highlighted, you can set both of these parameters
to the same value, and disable field re-drawing by using the
eighth parameter, flags.
The seventh parameter accepted by the od_edit_str() function,
character, will serve one of two purposes. Normally, this
parameter will specify a background character to display in the
unfilled portion at the end of the input field. This can be set
to a character, such as the ASCII 177 grey block character, to
produce a visual background to the field. Doing this will show
the user visually how long the field is, and how many character
they will be permitted to type into the field. Normally, this
field will be displayed during input, and removed when the
od_edit_str() function exits. However, you may cause the
background to remain in place using the eighth parameter, flags.
If you do not wish to have this "background" visual field effect,
simply set the character parameter to a space (ASCII 32). In
password input mode, this parameter will instead specify the
character to display in place of characters typed by the user. In
this case, the background display character defaults to the space
(ASCII 32) character.
The eighth, and last, parameter accepted by the od_edit_str()
function is the flags parameter. This parameter is a bit-mapped
flags variable which allows you to control special features of
the od_edit_str() function. More than one of these settings may
be specified by listing a chain of the values, separated by the
bitwise-or (|) operator. If you do not wish to turn on any of
these modes, simply pass the EDIT_FLAG_NORMAL value as the flags
parameter.
EDIT_FLAG_NORMAL - Default setting, use this value of none of the
other flags below are active.
EDIT_FLAG_NO_REDRAW - When set, prevents the od_edit_str()
function from re-drawing the input string and field
when it starts up and exits. If you set this flag, the
normal_colour and highlight colour should contain the
same value. If background character (the character
parameter) is not a space (ASCII 32) character, you
must draw the field background prior to calling
OpenDoors Door Toolkit Manual - Version 4.10 Page 56
od_edit_str(). Also, if you are calling od_edit_str()
with the EDIT_FLAG_EDIT_STRING flag set, you must
display the existing string in the field prior to
calling od_edit_str().
EDIT_FLAG_FIELD_MODE - Setting this flag specifies that
od_edit_str() should operate in field input mode. In
field input mode, the user may finish entering their
input by pressing the previous field or next field
button (arrow keys, tab keys, etc.), as described
above. If the user chooses to finish and accept their
input by pressing one of these keys, the od_edit_str()
return value will reflect which choice they made. This
will allow you to make it possible for the user to move
between a number of input fields in a form / dialog
box, as demonstrated in the example accompanying the
od_draw_box() function.
EDIT_FLAG_EDIT_STRING - Setting this flag specifies that
od_edit_str() should edit a pre-existing string,
instead of starting with a blank string. In this case,
the input_string parameter MUST point to an initialized
string. This string may either contain some text, or be
empty, but od_edit_str() will expect to find a string
terminator ('\0') character, and will begin editing the
contents of the string prior to that character. If you
do not set the EDIT_FLAG_EDIT_STRING flag, the previous
contents of the input_string parameter is not
significant, as od_edit_str() will automatically start
with a blank string.
EDIT_FLAG_STRICT_INPUT - Setting this flag causes the
od_edit_str() function to operate in "strict" input
mode, which may be desirable if your input format
contains more than one type of input. Normally, if you
were inputting such a string, the user would be able to
move to the middle of the string, and insert any text.
Doing so would cause the rest of the input line to
shift right. However, in cases where your format string
specifies different types of character to be permitted
in different positions, this can cause the input to be
changed so that it no longer conforms to the format
string. In this case, the user's input will no longer
be valid, and the user will not be able to exit the
function by pressing [ENTER] (although [ESCAPE] will
still be available, if you activated it) until they
change their input. However, when strict input mode is
turned on, od_edit_str() will restrict the ways in
which the user is permitted to edit the string, to
prevent just such a case from occurring.
EDIT_FLAG_PASSWORD_MODE - Setting this flag causes the
od_edit_str() function to operate in "password" mode.
In password mode, the characters typed by the user will
be hidden, displayed instead as the blank character
specified in the "character" parameter.
OpenDoors Door Toolkit Manual - Version 4.10 Page 57
EDIT_FLAG_ALLOW_CANCEL - When this flag is set, the user will be
able to cancel their current input and abort the
editing process by pressing their [ESCAPE] key. When
they do so, any changes they have made to the input
field will be cancelled, and replaced by the original
contents of the string. The od_edit_str() function will
then exit, indicating that the user has cancelled their
input.
EDIT_FLAG_FILL_STRING - When set, this flag will force the user
to enter a string that fills the entire length of the
format string. Normally, the user will be able to enter
a string of any length up to the maximum length
specified by the format string. However in some cases,
such as when inputting a date, you will want to have
the input field filled. (Otherwise, the user would be
able to enter only the first part of the date.)
EDIT_FLAG_AUTO_ENTER - When set, this flag will cause the
od_edit_str() function to automatically simulate
pressing of the [ENTER] key when the string is filled.
This can be used to cause the od_edit_str() function to
finish inputting as soon as a valid string is entered,
instead of having to wait for the user to press [ENTER]
/ [RETURN].
EDIT_FLAG_AUTO_DELETE - When set, along with the
EDIT_FLAG_EDIT_STRING flag, this flag will activate the
auto-delete feature of the od_edit_str() function. When
auto-delete is active, if the first key pressed by the
user is not an edit control key, the existing text will
automatically be deleted, and a totally new string
accepted from the user. This could be useful when you
are allowing the user to go back to edit a previous
input. If the user wishes to only change part of the
old string, they can move the cursor to the location
where they wish to make the change, and perform their
editing. However, if the user wishes to completely
replace the old string with a new one, they can simply
begin to type, and the old string will automatically be
deleted, and the new string accepted.
EDIT_FLAG_KEEP_BLANK - Normally, OpenDoors will only display the
input field background (as passed in the "character"
parameter) while the user is editing the string, and
will remove it when the od_edit_str() function exits.
However, you may wish to continue having this field
displayed after input has taken place, and the
od_edit_str() function has exited. In this case,
setting this flag will cause the background characters
to remain visible after input has finished.
EDIT_FLAG_PERMALITERAL - When the format string contains literal
characters (such as forcing a ':' character to be added
to a time input by using the format string
OpenDoors Door Toolkit Manual - Version 4.10 Page 58
"##':'##':'##"), the od_edit_str() function can operate
in one of two modes. In the default mode, the literal
characters will only be displayed when they have been
automatically added to the string. For instance, if you
were inputting the current time using the above format
string, this mode would result in the input field
initially being blank. When the user types the first
digit of the time, that number would appear. When the
user types the second digit of the time, that number
will appear, and then the colon character will
automatically be added by OpenDoors. However, you can
also set the od_edit_str() function to operate in
"PermaLiteral" mode, by setting this flag. When the
EDIT_FLAG_PERMALITERAL flag is set, the input field
will initially contain the literal characters (ie, the
colons in our example), with the cursor still located
at the leftmost position in the input field. In this
mode, the literal character become a permanent part of
the input field, and can not be moved or deleted by the
user - instead the cursor simply skips over the literal
character's position.
EDIT_FLAG_LEAVE_BLANK - This flag applies to the special case
where the first character or characters of the format
string are literals. By default, the od_edit_str()
function will always return a string containing at
least these first literal characters. However, you can
alter this behavious by setting this flag. When set, if
no non-literal characters have been entered in the
string, od_edit_str() will return an empty string.
SEE ALSO od_input_str(), od_get_char(), od_clear_keybuffer()
EXAMPLE Below are several examples of typical uses of the od_edit_str()
function. For the sake of simplicity, all of these examples
perform their input beginning at the top, left hand corner of the
screen, and store the user's input in the string variable named
"string". For an example of the user of the od_edit_str()
function in a dialog-box / form entry application, see the
example accompanying the od_draw_box() function.
To input a name with a maximum of 25 characters, having the first
letter of each word automatically capitalized:
od_edit_str(string, "MMMMMMMMMMMMMMMMMMMMMMMMM", 1, 1,
0x03, 0x21, 176, EDIT_FLAG_NORMAL);
To input a North American style phone number, requiring that all
digits be filled, and running in "strict input" mode:
od_edit_str(string, "###'-'###'-'####",
1, 1, 0x03, 0x21, 176,
EDIT_FLAG_FILL_STRING|
OpenDoors Door Toolkit Manual - Version 4.10 Page 59
EDIT_FLAG_STRICT_INPUT);
To allow the user to edit a previously entered 20 character
string, with auto-delete mode on. Any characters will be
permitted in the string. Remember that when the
EDIT_FLAG_EDIT_STRING flag is set, the string must be initialized
prior to calling the od_edit_str() function.
od_edit_str(string, "????????????????????",
1, 1, 0x03, 0x21, 176,
EDIT_FLAG_EDIT_STRING|
EDIT_FLAG_AUTO_DELETE);
To input a password of up to 16 characters from the user. Here,
the password will only be permitted to contain upper case
characters, and the od_edit_str() password mode is used, with a
small block displayed in place of any characters typed:
od_edit_str(string, "UUUUUUUUUUUUUUUU",
1, 1, 0x03, 0x21, 254,
EDIT_FLAG_PASSWORD_MODE);
To input a two-digit number from the user, requiring that both
digits be filled, and automatically accepting the input after the
two digits have been entered (not requiring the user to press
[ENTER]):
od_edit_str(string, "##", 1, 1, 0x03, 0x21, 176,
EDIT_FLAG_FILL_STRING|
EDIT_FLAG_AUTO_ENTER);
To input a filename to download, as a field in a dialog box.
Here, the filename will be permitted to contain valid filename
characters, and the od_input_str() function will operate in field
mode, with the cancel [ESCape] key enabled. Also, string edit
mode will be enabled, allowing the user to edit a previously
entered line, and the EDIT_FLAG_KEEP_BLANK flag will be set,
causing the field background to remain displayed after the user
exits. This time, however, auto-delete mode will not be used.
Note that this combination of parameters expects that the field
and it's contents will have already been displayed, prior to
calling the od_edit_str() function.
od_edit_str(string, "WWWWWWWWWWWW",
1, 1, 0x03, 0x21, 176,
EDIT_FLAG_EDIT_STRING|
EDIT_FLAG_FIELD_MODE|
EDIT_FLAG_ALLOW_CANCEL|
EDIT_FLAG_KEEP_BLANK);
OpenDoors Door Toolkit Manual - Version 4.10 Page 60
To input a string without the field background and line redrawing
before and after input takes place:
od_edit_str(string, "******************************",
1, 1, 0x07, 0x07, ' ',
EDIT_FLAG_NO_REDRAW);
To input a date, using permaliteral mode. Here, the month is
entered by a three digit short form ("JAN", "FEB", etc.), and the
literal characters such as the '-' and the "19" are a permanent
part of the input field:
od_edit_str(string,"UUU'-'##'-19'##",
1, 1, 0x03, 0x21, 176,
EDIT_FLAG_PERMALITERAL|
EDIT_FLAG_FILL_STRING);
OpenDoors Door Toolkit Manual - Version 4.10 Page 61
OD_EMULATE()
--------------------------------------------------------------------------------
PURPOSE Displays a character with ANSI/AVATAR emulation
FORMAT void od_emulate(register char in_char);
RETURNS N/A
DESCRIPTION od_emulate() is a low-level function which allows you to display
your own ANSI / AVATAR graphics sequences and QBBS/RA style
control characters. This function passes the characters you wish
to display to the OpenDoors terminal emulator, which is fully
documented in the description of the od_send_file() function, on
page 101. As a result, this function can be used to send these
control sequences to the user's terminal, and also have them
displayed on the local screen as they will appear to the user.
The characters passed to the od_emulate() function will both be
sent directly to the modem, and sent to the local screen, after
being translated by the terminal emulator. Thus, if you were to
send the characters ESCape,[,2,;,4,H to the emulator using this
function, the cursor would be positioned at location 2 by 4 (on
both the local and remote screens). Note that this function only
accepts a single character at a time. The example below
demonstrates a function to send an entire string of characters
using the od_emulate() function.
Note that if you wish to display an entire file containing
ANSI/AVATAR graphics sequences (perhaps as your door's menu or
title screen), use the od_send_file() function.
SEE ALSO od_send_file(), od_disp(), od_disp_str() od_printf(), od_putch(),
od_repeat().
For a breakdown of the uses of the various OpenDoors display
functions, see the od_disp_str() function, on page 46.
EXAMPLE Below is an example of a function which will allow you do display
strings of ANSI or AVATAR sequences, using the od_emulate()
function:
void emulate_string(char *pointer)
{ /* loop through string, sending each character */
while(*pointer) od_emulate(*pointer++);
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 62
Using this function you could have an ANSI sequence sent to the
user's terminal program, and displayed on the local screen as it
would appear on the user's screen. For example, to display the
ANSI sequence of ESCape followed by "[2;4H", which just happens
to move the cursor to location 2 by 4, you could:
emulate_string("\x1b[2;4H");
(Note that \x1b represents the ESCape character, ASCII 27 or 1B
in hexidecimal.)
OpenDoors Door Toolkit Manual - Version 4.10 Page 63
OD_EXIT()
--------------------------------------------------------------------------------
PURPOSE The OpenDoors program termination function
FORMAT void od_exit(int errorlevel,char term_call);
RETURNS N/A
DESCRIPTION When writing a door program, you MUST USE THIS FUNCTION when you
want your Door to exit. This function will deinitialize the
fossil driver, re-write changed information to the EXITINFO.BBS
file, call your end-of-program function (if any), and then exit
with the errorlevel specified in the first parameter.
Also, if the second parameter, "term_call", is set to TRUE,
od_exit() will also log the user off (for options such as logging
off within the door - as shown in the example below). This is
accomplished by lowering the DTR line to the modem, causing the
modem to hangup. When control is returned to the BBS, it will
then detect that the user is no longer online, and will carry out
its own logoff processing.
If you wish for your program to always perform any activities
prior to exiting, such as updating or closing data files, you
should set a function to be executed from within the od_exit()
function. This is accomplished by using the od_control.
od_before_exit variable, as described in the section on the
OpenDoors control structure in chapter 5. Use of this variable
will allow your program to always carry out these activates, even
if OpenDoors decides to call the od_exit() function itself, such
as when a user hangs up on the door.
Note that in special cases, you may use the od_control.od_disable
variable to prevent the od_exit() function from re-writing the
door information file. Also, you may use the od_control.od_noexit
variable to shutdown door operations without actually exiting
your program. Both of these variables are described in chapter 5.
This function should not be used in utility program that only use
the BBS interface module of OpenDoors, nor with any program that
has not previously called the od_init(), or some other OpenDoors
DOOR DRIVER function.
SEE ALSO od_init()
OpenDoors Door Toolkit Manual - Version 4.10 Page 64
EXAMPLE The example below demonstrates a function which a door could
execute when the user chooses to exit the door. This function
will ask the user whether they wish to exit the door and return
to the BBS, simply logoff of the BBS, or continue using the door.
The example function will then call od_exit() if the user wishes
to exit the door, or return control to the function which called
it, if the user does not wish to exit:
void goodbye(void)
{
char pressed;
/* Display choices to user */
od_disp_str("You have chosen to exit this door.\n\r");
od_disp_str("Do you wish to:\n\r");
od_disp_str(" [R]eturn to the BBS\n\r");
od_disp_str(" [L]ogoff of the BBS\n\r");
od_disp_str(" [C]ontinue using the door\n\r");
for(;;) /* loop until user makes valid choice */
{
pressed=od_get_key(TRUE); /* Get key from user */
/* If user selects R, exit without hanging up */
if(pressed=='R' || pressed=='r') od_exit(40,FALSE);
/* If user selects L, hangup and then exit */
if(pressed=='L' || pressed=='l') od_exit(41,TRUE);
/* If user selects C, return and allow door to continue */
if(pressed=='C' || pressed=='c') return;
}
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 65
OD_GET_ANSWER()
--------------------------------------------------------------------------------
PURPOSE Function to allow the user to respond to a prompt using only
certain keys.
FORMAT char od_get_answer(char *string);
RETURNS User's response to prompt
DESCRIPTION This function can be used to get a response from the user, when
only particular responses should be accepted. The parameter to
the od_get_answer() function is simply a string listing the valid
responses. The function will wait until the user selects one of
the valid responses, and then return that response. The function
is case insensitive, and will return the character in the same
case that was supplied to it in the string.
SEE ALSO od_get_key(), od_hotkey_menu()
EXAMPLES od_get_answer("YN");
- If the user presses 'y', will return 'Y'.
od_get_answer("yn");
- If the user presses 'y', will return 'y'.
od_get_answer("ABC 123\nZ");
- Valid responses will be: [A], [B], [C], [SPACE],
[1], [2], [3], [ENTER], [Z]
OpenDoors Door Toolkit Manual - Version 4.10 Page 66
OD_GET_KEY()
--------------------------------------------------------------------------------
PURPOSE Function to input a key from the user
FORMAT int od_get_key(int wait);
RETURNS The next key waiting from the keyboard, or 0 if none.
DESCRIPTION This function retrieves the next key waiting in the OpenDoors
keyboard buffer (see the description of the od_clear_keybuffer()
function, on page 38, for more information on the OpenDoors
keyboard buffer). The od_get_key() function allows your door to
retrieve both those keystrokes pressed by the user, and the
keystrokes pressed on the sysop keyboard (other than the sysop
function keys), in the sequence they were pressed. Since input is
accepted from both sources, it is possible for the sysop, as well
as the remote user, to make selections and control the door.
Door input with OpenDoors can be accomplished with this function,
with the od_input_str() function or with the od_edit_str()
function. The od_input_str() and od_edit_str() functions is used
to input an entire sequence of characters from the user (a
string), and requires the user to press the [Enter] key when they
are finished typing their input. On the other hand, the
od_get_key() function is used to input a single keystroke (one
character) from the user, and allows the user to make choices
without having to press the enter key.
The od_get_key() function accepts a single parameter, which
determines whether or not it should wait for the user to press a
key, if they have not already done so. If you pass a FALSE value
to od_get_key(), then the function will not wait for a key to be
pressed at the keyboard, but instead return a 0 if there are no
keys waiting in the buffer. If you pass a TRUE value to
od_get_key(), then this function will instead wait for a key to
be pressed. Also, while waiting for the user to press a key, the
od_get_key() function will give up the processor to other waiting
programs, if you door is running under DesqView.
If you are waiting for the user to make a choice from a menu or
list of options, you will most likely pass a TRUE to the
od_get_key() function, indicating that you wish for it to wait
until a key is pressed. However, if you wish to continue other
processing if no key is yet available from the keyboard, you
should pass a FALSE to the od_get_key() function. For example, if
you are displaying a screen of text, and wish to allow the user
to pause or abort the display, you would simply call the
od_get_key() function every few moments, passing it a value of
FALSE. You would then be able to check if any control keys have
been pressed, and if not, continue displaying text.
OpenDoors Door Toolkit Manual - Version 4.10 Page 67
The od_get_key() function returns the ASCII value representing
the keystroke that was made. If you are waiting for the user to
make a particular choice, perhaps from a menu, you will most
likely store the value returned by od_get_key() in a variable of
type char. For example:
char key;
...
key=od_get_key(TRUE);
You would then be able to determine which key the user pressed by
testing the value of key, either by comparing it's numerical
ASCII value, or by comparing it to a character constant. If you
are testing for a non-character key, such as [ESCape], [Tab] or
[Return], you may wish to use the ASCII value of that key. For
example, if you wished to take some action in the case that the
user presses the [Enter]/[Return] key, who's ASCII value is 13,
you could do:
key=od_get_key(TRUE); /* Get keypress from user */
if(key==13) /* If key was [Enter]/[Return] */
{
... /* Whatever you want to do */
}
A complete reference of all the ASCII values is listed below.
To determine whether input originated from the local or remote
keyboards, see the OpenDoors control structure variable
od_last_input.
If you wish, instead, to respond to the user pressing a character
key (perhaps as a choice from a menu), you can do so by using
character constants, such as 'c', '6', or 'F'. Also, when testing
for an alphabetical character, you will probably want to check
for the user pressing either the upper or lower-case version of
the letter. For example, if you wished to have the user press the
[Y] key to continue, you could test for either an upper or lower-
case Y as follows:
key=od_get_key(TRUE); /* Get keypress from user */
if(key=='y" || key=='Y") /* If key was [y]/[Y] */
{
... /* Whatever you want to do */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 68
The chart below lists the decimal value and corresponding keystroke(s) of each
of the ASCII values from 0 to 127.
ASCII KEYSTROKE | ASCII KEYSTROKE
----- ------------------------------ | ----- ----------------------
0 [Control]-[@] | 15 [Control]-[O]
1 [Control]-[A] | 16 [Control]-[P]
2 [Control]-[B] | 17 [Control]-[Q]
3 [Control]-[C] | 18 [Control]-[R]
4 [Control]-[D] | 19 [Control]-[S]
5 [Control]-[E] | 20 [Control]-[T]
6 [Control]-[F] | 21 [Control]-[U]
7 [Control]-[G] | 22 [Control]-[V]
8 [Control]-[H]/[Backspace] | 23 [Control]-[W]
9 [Control]-[I]/[Tab] | 24 [Control]-[X]
10 [Control]-[J] | 25 [Control]-[Y]
11 [Control]-[K] | 26 [Control]-[Z]
12 [Control]-[L] | 27 [ESCape]
13 [Control]-[M]/[Enter]/[Return] | 32 [SpaceBar]
14 [Control]-[N] |
ASCII KEYSTROKE | ASCII KEYSTROKE | ASCII KEYSTROKE | ASCII KEYSTROKE
----- --------- | ----- --------- | ----- --------- | ----- ---------
33 '!' | 57 '9' | 80 'P' | 104 'h'
34 '"' | 58 ':' | 81 'Q' | 105 'i'
35 '#' | 59 ';' | 82 'R' | 106 'j'
36 '$' | 60 '<' | 83 'S' | 107 'k'
37 '%' | 61 '=' | 84 'T' | 108 'l'
38 '&' | 62 '>' | 85 'U' | 109 'm'
39 '\'' (') | 63 '?' | 86 'V' | 110 'n'
40 '(' | 64 '@' | 87 'W' | 111 'o'
41 ')' | 65 'A' | 88 'X' | 112 'p'
42 '*' | 66 'B' | 89 'Y' | 113 'q'
43 '+' | 67 'C' | 90 'Z' | 114 'r'
44 ',' | 68 'D' | 91 '[' | 115 's'
45 '-' | 69 'E' | 92 '\\' (\) | 116 't'
46 '.' | 70 'F' | 93 ']' | 117 'u'
47 '/' | 71 'G' | 94 '^' | 118 'v'
48 '0' | 72 'H' | 95 '_' | 119 'w'
49 '1' | 73 'I' | 96 '`' | 120 'x'
50 '2' | 74 'J' | 98 'b' | 121 'y'
51 '3' | 75 'K' | 99 'c' | 122 'z'
52 '4' | 76 'L' | 100 'd' | 123 '{'
53 '5' | 77 'M' | 101 'e' | 124 '|'
54 '6' | 78 'N' | 102 'f' | 125 '}'
55 '7' | 79 'O' | 103 'g' | 126 '~'
56 '8' | | | 127 [DELete]
OpenDoors Door Toolkit Manual - Version 4.10 Page 69
SEE ALSO od_input_str(), od_edit_str(), od_clear_keybuffer()
EXAMPLE For examples of the use of the od_get_key() function, see the
examples in the description portion, above, and the examples for
the od_exit() and od_clear_keybuffer() functions. For further
examples of this function, see the example door EZVote, described
in the section beginning on page 25.
OpenDoors Door Toolkit Manual - Version 4.10 Page 70
OD_HOTKEY_MENU()
--------------------------------------------------------------------------------
PURPOSE Function to display a menu file with hotkeys
FORMAT char od_hotkey_menu(char *filename, char *hotkeys, char wait);
RETURNS Key pressed in response to menu, or '\0' if none.
DESCRIPTION This function can be used to display a menu from an ASCII, ANSI
or AVATAR file, allowing the user to select an option at any time
while the menu is being displayed. The od_hotkey_menu() function
is quite similar to the od_send_file() function, and you should
probably familiarize yourself with that function if you are going
to use od_hotkey_menu(). Like od_send_file(), od_hotkey_menu()
will display the file specified by filename, using the
appropriate terminal emulation. If no extention is provided for
the filename, OpenDoors will automatically search for matching
files ending in .ASC, .ANS and .AVT extentions. OpenDoors will
the select the appropriate file to display, based on the
available files and available terminal emulation.
The second parameter, hotkeys, is a string specifying the valid
responses to the menu, in the same format as the string passed to
the od_get_answer() function. If any of the characters listed in
this string are pressed, either uppercase or lowercase versions,
OpenDoors will immediately stop displaying the menu, and return
with the value of the key pressed. The case (upper or lower)
returned will always be identical to the case used in the hotkeys
string. You can include the [ENTER] key as a valid hot key by
including the \n character in the hotkey string.
The third parameter passed to od_hotkey_menu(), wait, specifies
whether OpenDoors should wait after displaying the menu for the
user to make a valid selection from the menu (TRUE), or if it
should exit immediately (FALSE). Normally, you will want to use
the TRUE value when calling this function. This will allow you to
use a single function call that will display the menu and always
return the user's selection. If you wish to gain control as soon
as OpenDoors has displayed the menu and sent it to the FOSSIL
driver, you may specify FALSE for this parameter. In this case,
if the user does not press any of the valid hot keys while the
menu is being sent, the function will return the character '\0'.
SEE ALSO od_send_file(), od_get_answer()
OpenDoors Door Toolkit Manual - Version 4.10 Page 71
EXAMPLE As an example of the use of the od_hotkey_menu() function,
consider the following code fragment:
for(;;) /* Main pogram loop */
{ /* Display menu and get user's choice */
char choice=od_hotkey_menu("MAINMENU","123Q",TRUE");
switch(choice) /* Perform the appropriate action */
{
case '1':
od_printf("You selected one.\n\r");
break;
case '2':
od_printf("You selected two.\n\r");
break;
case '3':
od_printf("You selected three.\n\r");
break;
case 'Q':
od_exit(FALSE,10);
}
}
This is an example of the main menu loop of a simple door that
uses the od_hotkey_menu() function. The program will continue
executing the for(;;) loop until the user chooses to exit the
door. On each iteration of the loop, the od_hotkey_menu()
function is called, to display the door's menu from the file
MAINMENU.A??. The appropriate .ASC/.ANS/.AVT file will be chosen
and displayed as the menu. The possible choices that may be made
from the menu are specified by the string "123Q". Thus, whenever
the user presses one of the keys [1], [2], [3] or [Q], the
od_hotkey_menu() function will return immediately with the value
of the key pressed. If the menu is still being displayed at the
time when the key was pressed, menu display will cease at that
moment. The program then executes a case statement, to respond to
the user's key appropriately. If the user presses [1], [2] or [3]
this door will output a simple message to the screen. If the user
presses the [Q] key, the door will pass control back to the BBS.
OpenDoors Door Toolkit Manual - Version 4.10 Page 72
OD_INIT()
--------------------------------------------------------------------------------
PURPOSE To initialize OpenDoors activities
FORMAT void od_init(void);
RETURNS N/A
DESCRIPTION This function initializes any door running under OpenDoors. This
function must be called manually if you wish to access data about
the user, etc., before you call any other OpenDoors functions.
However, if you do not explicitly call the od_init() function, it
will be called automatically on the first call to any other
OpenDoors door driver function. The od_init() function reads
information from the door information file, initializes
communications with the modem, displays the status line, and sets
up OpenDoors' internal data structures. For more information on
what data is and is not available before od_init() has been
called, please refer to the chapter on the OpenDoors control
structure, which begins on page 119.
The od_init() function will read the door information file which
is located in the directory specified by the variable
od_control.info_path. If this variable has not been set prior to
calling the od_init() function, OpenDoors will expect to find the
door information file in the current directory. Thus, if you wish
your door to be able to be run in a directory other than the BBS
system directory, it would be a good idea to allow the sysop
using your door to specify the location of the door information
file. For an example of setting the od_control.info_path
variable, please see the example program located on page 122.
Note that the od_init() function should not be called in any
utility-only program (ie, programs which only use the BBS
interface module of OpenDoors), or when you wish for your door
program to run in "maintenance mode", as described and
demonstrated in the example below.
Also note that you can prevent the od_init() function from
carrying out some of it's normal activities, such as attempting
to read a door information file, by the use of the
od_control.od_disable variable, as described in the section on
the OpenDoors control structure, which begins on page 119.
SEE ALSO od_exit()
OpenDoors Door Toolkit Manual - Version 4.10 Page 73
EXAMPLE At times, you may wish to write a door program which will require
a maintenance utility to be run on a regular basis. For example,
a game door may have to have its system files updated on a daily
basis, by having a utility program run in a system event each day
at midnight. One way of accomplishing this would be to have your
door package include two .EXE files, one being the actual door
program, and the other being a utility program. However, another
option would be to have both the door and maintenance functions
to be accessible from a single .EXE file, in order to simplify
use of the door for the sysop. In this case, you would want to
test the command line to determine whether your program should
run in door mode or maintenance mode. You would then only execute
the od_init() function, along with the rest of your door code, if
you program were running in "door mode".
The program below demonstrates one method of doing just this. In
this case, the program would include two functions, door(), which
would carry out all of the door-related activities, and maint(),
which would carry out all of the maintenance-related activities.
In this simple example, if the command line includes a "-M" or
"/M", the program will run in maintenance mode, otherwise it will
run in door mode. Also, if it is running in door mode, the
program will take the first command-line parameter, if any, as a
path to the location of the door information file.
#include "opendoor.h"
void door(void);
void maint(void);
int main(int argc, char *argv[])
{
int counter;
/* Check any command line parameters for /M or -M */
for(counter=1;counter<argc;++counter)
{
if((argv[counter])[1]=='m' || (argv[counter])[1]=='M')
{
maint(); /* Then carry out maintenance */
exit(20); /* And exit */
}
}
/* If there was no -M or /M, then run in door mode */
/* If there are any command-line parameters, take the first */
/* as the path to the door information file */
if(argc>1) strncpy(od_control.info_path,argv[1],59);
od_init(); /* call the od_init() function */
door(); /* Run the door portion of the program */
od_exit(30,FALSE); /* Shutdown the door */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 74
void maint(void)
{
... /* Carry out maintenance activities here */
}
void door(void)
{
... /* Carry out door activities here */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 75
OD_INIT_WITH_CONFIG()
--------------------------------------------------------------------------------
PURPOSE To initialize OpenDoors activities, parsing a configuration file.
FORMAT void od_init_with_config(char *filename,
(*custom_line_function) (char *keyword,char *options) );
RETURNS N/A
DESCRIPTION This function can be used instead of the od_init() function, to
begin OpenDoor's operations. This function performs all of the
initialization activities that the od_init() function does, and
also reads any information in the door's configuration file. The
configuration file system automatically provides support for a
considerable number of sysop configurable options, such as system
directories, BBS information, display colours, custom door
information file formats, maximum time within the door, and so
on. To familiarize yourself more with the OpenDoors configuration
file format, it is suggested that you examine the example
configuration file, EZVOTE.CFG. Feel free to distribute the
EZVOTE.CFG or a modified version of the file with your own doors.
The od_init_with_config() function accepts two parameters. The
first parameter specifies the name of the configuration file that
OpenDoors should look for. If no configuration file is found, the
od_init_with_config() will continue initialization normally,
using the default settings. This means that the configuration
file is always optional, and that OpenDoors is designed to
continue normally if the sysop elects not to use a configuration
file.
OpenDoors will first search for the configuration file in the
directory specified on the od_init_with_config() command line. If
the configuration file is not found there, OpenDoors will search
in the current dirrectory. If the configuration file is still not
found, it will then look for the file in the directory where the
door's .EXE file is located.
The format for the configuration file is as follows. Blank lines
and any text following the semi-colon (;) character are ignored.
Configuration options are specified using a keyword, possibly
followed by one or more options. The keywords are not case
sensitve, but some of the options are. The order of options in
the configuration file is not significant. The built-in
configuration options are as follow:
BBSDir - BBS System directory. Indicates where the door
information file (drop file) can be found.
OpenDoors Door Toolkit Manual - Version 4.10 Page 76
DoorDir - The door's working directory. This is where the door's
system files are located. OpenDoors will automaticaly
perform a chdir into this directory at initialization, and
will return to the original directory on exit.
LogFileName - Specifies the filename (path optional) where the
door should record log information.
DisableLogging - Prevents door from writing to a log file.
Node - BBS node number that the door is running on. Only used if
OpenDoors is unable to determine the node number by some
other means.
???dayPagingHours - Specifies sysop paging hours. Sysop paging
will be permitted beginning at the start time, up until, but
not including, the end time. Times should be in the 24-hour
format. To disable paging on a particular day, set the
paging start and end times to the same time. ???day can be
one of Sunday, Monday, Tuesday, Wednesday, Thursday, Friday
or Saturday.
PagDuration - Duration of sysop page. Value indicates the number
of beeps that compose the sysop page alarm.
MaximumDoorTime - Maximum length of time a user is permitted to
access the door. If the user's total remaining time on the
BBS is less than this value, the user will only be permitted
to access the door for this shorter length of time. This
option is disabled by commenting out the line.
InactivityTimeout - Specifies the maximum number of seconds that
may elapse without the user pressing a key, before the user
will automatically be disconnected. A value of 0 disables
inactivity timeouts.
SysopName - Name of the sysop. OpenDoors can usually determine
the sysop's name from the door information (drop) file.
How3ever, some BBS packages do not supply this information.
In such cases, if the sysop's name is required by the door,
it may be supplied here.
SystemName - Like the sysop's name, this option can usually be
determined from the door information file. If it is not
available, the sysop my supply the information here.
ChatUserColour - Specifies the colour of text typed by the user
in sysop chat mode. The format of the colour name is
included in the description of the od_colour_config()
function.
ChatSysopColour - Specifies the colour of test typed by the sysop
in chat mode.
FileListTitleColour - Files.BBS listing colours.
OpenDoors Door Toolkit Manual - Version 4.10 Page 77
FileListNameColour
FileListSizeColour
FileListDescriptionColour
FileListOfflineColour
SwappingDir - Directory where disk swapping will be done.
SwappingNoEMS - Disables swapping to EMS memory.
SwappingDisable - Disables swapping entirely.
LockedBPS - BPS rate at which door should communicate with the
modem. Valid rates are 300, 600, 1200, 2400, 4800, 9600,
19200 and 38400. A value of 0 forces the door to always
operate in local mode. This option is not normally needed,
as the information is usually available from the door
information file.
FossilPort - Specifies the FOSSIL driver prot number tha tthe
modem is connected to. FOSSIL port 0 usually corresponds to
COM!, port 1 to COM2, and so on. This option is not normally
needed, as the information is usually available from the
door information file.
CustomFileName - Specifies the filename used by the custom door
information file format. Described in more detail below.
CustomFileLine - Specifies the contents of a particular line in
the custom door information file format.
Two of the most powerful options of the configuration file are
those that allow the sysop to specify a custom door information
file format. To permit OpenDoors doors to operate on BBS systems
that produce a door information file format not directly
supported by OpenDoors, the sysop may define a custom door
information file format. A custom door information file format is
defined using the "CustomFileName" option, followed by one or
more lines beginning with the "CustomFileLine" option.
The "CustomFileName" option specifies the filename used to
distinguish this file format from other file formats. This
filename should not include a path. To specify the path where the
door information file is located, use the BBSDir setting, near
the beginning of this file. If the filename of the custom format
is the same as that of one of the built-in formats, the custom
format will override the built-in format.
The actual format of the custom file is specified using a number
of lines that begin with the keyword "CustomFileLine". Each of
these lines will correspond to a single line in the door
information file, with the option following the "CustomFileLine"
keyword specifying the information that can
be found on that line. This can be one of the following keywords:
OpenDoors Door Toolkit Manual - Version 4.10 Page 78
Ignore - Causes the next line in the door information file
to be ignored. Use on lines for which none of the
options below apply.
COMPORT - COM? port the modem is connected to (0 indicates
local mode)
FOSSILPORT - Fossil port number the modem is connected to
MODEMBPS - BPS rate at which to communicate with modem (0 or
non-numerical value indicates local mode)
LOCALMODE - 1, T or Y if door is operating in local mode
USERNAME - Full name of the user
USERFIRSTNAME - First name(s) of the user
USERLASTNAME - Last name of the user
ALIAS - The user's psuedonym / handle
HOURSLEFT - Hours user has left online
MINUTESLEFT - Minutes user has left online, or time left
online in format hh:mm
SECONDSLEFT - Seconds user has left online, or time left
online in format hh:mm:ss or format mm:ss (If more than
one of the above time options are used, the user time
left is taken to be the total of all of these values.)
ANSI - 1, T, Y or G for ANSI graphics mode
AVATAR - 1, T or Y for AVATAR graphics mode
PAGEPAUSING - 1, T or Y if user wishes a pause at end of
screen
SCREENLENGTH - Number of lines on user's screen
SCREENCLEARING - 1, T or Y if screen clearing mode is on
SECURITY - The user's security level / access level
CITY - City the user is calling from
NAME - Node number user is connected to
SYSOPNAME - Full name of the sysop
SYSOPFIRSTNAME - The sysop's first name(s)
SYSOPLASTNAME - The sysop's last name
SYSTEMNAME - Name of the BBS
OpenDoors Door Toolkit Manual - Version 4.10 Page 79
You can also extend OpenDoor's configuration file format to add
your own option, by supplying od_init_with_config with a custom
line function. A pointer to the custom line function is provided
as the second parameter to the od_init_with_config() function. If
you do not wish to add any custom lines to the configuration
file, simply pass the value NULL to the function. For an example
of implementing a custom line function, the example code at the
end of this section on configuration files. The custom line
function should accept two pointers to strings and return "void".
If a custom line function has been specified, whenever the
configuration file system encounters an unknown configuration
option, it will call your custom line function. The first
parameter that the configuration system passes to your function
is a pointer to the string containing the keyword found, in upper
case. The second parameter will be the text of the configuration
file line. For instance, if the following line were encountered
in the configuration file:
RegisteredTo John Smith ; Sysop's name
The parameters passed to your function would be:
char *keyword = "REGISTEREDTO"
char *options = "John Smith"
Your custom line function should be written in such a way that if
OpenDoors passes a configuration option to your function that
your function does not recognize, that option should simply be
ignored.
All of the keywords used within the OpenDoors configuration file
are language customizable. These prompts are specified in two
global variables, od_config_text and od_config_lines. The default
definitions for these arrays are as follows:
char *od_config_text[12]={"Node",
"BBSDir",
"DoorDir",
"LogFileName",
"DisableLogging",
"SundayPagingHours",
"MondayPagingHours",
"TuesdayPagingHours",
"WednesdayPagingHours",
"ThursdayPagingHours",
"FridayPagingHours",
"SaturdayPagingHours",
"MaximumDoorTime",
"SysopName",
"SystemName",
"SwappingDisable",
"SwappingDir",
"SwappingNoEMS",
"LockedBPS",
OpenDoors Door Toolkit Manual - Version 4.10 Page 80
"FossilPort",
"CustomFileName",
"CustomFileLine",
"InactivityTimeout",
"PageDuration"};
char *od_config_lines[24]={"Ignore",
"ComPort",
"FossilPort",
"ModemBPS",
"LocalMode",
"UserName",
"UserFirstName",
"UserLastName",
"Alias",
"HoursLeft",
"MinutesLeft",
"SecondsLeft",
"ANSI",
"AVATAR",
"PagePausing",
"ScreenLength",
"ScreenClearing",
"Security",
"City",
"Node",
"SysopName",
"SysopFirstName",
"SysopLastName",
"SystemName"};
SEE ALSO od_init(), od_colour_config()
EXAMPLE Below is an example of using a custom line function to add
additional options to the default settings in the configuration
file.
#include "opendoor.h" /* Include opendooor.h */
/* Prototype for custom line funciton */
void custom_line_function(char *keyword, char *options);
unsigned long key=0L; /* Variables for our own config opation */
unsigned char default_colour=0x07;
char display_winners=FALSE;
main() /* Program's execution begins here */
{ /* Begin door operations, reading config file */
od_init_with_config("DOOR.CFG",custom_line_function);
/* Main program's operations go here */
od_exit(FALSE,10); /* Exit door */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 81
/* Code for custom line function */
void custom_line_function(char *keyword, char *options)
{ /* If option is registration key */
if(strcmp(keyword,"REGISTRATIONKEY")==0)
{
key=atol(options); /* Store key in variable */
} /* If option is text colour */
else if(strcmp(keyword,"DEFAULTCOLOUR")==0)
{ /* Get colour value using od_colour_config() */
default_colour=od_colour_config(options);
} /* Example of option enabled by just the keyword */
else if(strcmp(keyword,"DISPLAYWINNERS")==0)
{ /* If keyword is present, turn on option */
display_winners=TRUE;
}
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 82
OD_INPUT_STR()
--------------------------------------------------------------------------------
PURPOSE Inputs a string from the user
FORMAT void od_input_str(char *string,int max_len,char minchar, char
maxchar);
RETURNS N/A
DESCRIPTION To perform string input within OpenDoors, one of two functions
can be used, od_input_str() and od_edit_str(). The first
function, od_input_str(), allows simple line input and editing,
and can be used in ASCII, ANSI and AVATAR modes. The second
function, od_edit_str(), allows many formatted input options,
advanced line editing, and other features, but requires the use
of ANSI or AVATAR graphics modes.
The od_input_str() function allows you to input a string from the
user. The string will be permitted to have up to the number of
characters specified by the max_len parameter, and all characters
must be between the values of the min_char and max_char
parameters. This function will wait until the user presses the
[Enter] key to finish inputting the string.
The first parameter passed to this function should be a pointer
to the string where the user's input should be stored. So, if you
wanted to store a string of up to 30 characters inputted by the
user, you might define this string as follows:
char input_string[31];
Notice here than the string must be long enough to hold the
thirty characters which can be entered by the user, along with
the additional "null" character which is used to indicate the end
of a string in C. Hence, the length of the string should always
be at least one greater than the total number of characters the
user is permitted to enter, passed in the max_len parameter.
The second parameter passed to the od_input_str() function should
be an integer value indicating the maximum number of characters
which can be input by the user. For example, if this parameter
had a value of 10, the user would be able to enter a string
containing any number of characters up to and including 10
characters. If this parameter had a value of 1, the user would
only be able to enter a single character. However, the user would
be able to backspace, change the character, and press [Enter]
when they were satisfied with their entry. Note that even if you
only ask the od_input_str() function to input a single character,
OpenDoors Door Toolkit Manual - Version 4.10 Page 83
it will still expect a STRING to be passed to it, and will return
a string with either zero or one character, followed by a null
(string terminator) character.
The third and fourth parameters passed to this function allow you
to control what characters the user will be permitted to enter as
part of the string. For example, you could set the minimum
character to the '0' character and the maximum character to the
'9' character, permitting the user to only enter numeric
characters. On the other hand, you could permit the user to enter
all ASCII characters in the range from 32 to 127. The
od_input_str() function will permit characters in the range
beginning with the character passed as minchar, up to and
including the character passed as maxchar.
SEE ALSO od_edit_str(), od_get_key(), od_clear_keybuffer()
EXAMPLE Below are a number of examples of the use of the od_input_str()
function in various applications:
- To input a two character number (only digits from 0-9):
od_input_str(string,2,'0','9');
- To input a 35 character name (characters from Space to
ASCII 127):
od_input_str(string,35,32,127);
OpenDoors Door Toolkit Manual - Version 4.10 Page 84
OD_KERNAL()
--------------------------------------------------------------------------------
PURPOSE The OpenDoors Central Control function
FORMAT void od_kernal(void);
RETURNS N/A
DESCRIPTION The od_kernal() function is responsible for many vital OpenDoors
tasks, such as monitoring the carrier detect signal, monitoring
the amount of time that the user has remaining, updating the
status line, responding to sysop hotkeys, and reading characters
which are received from the modem. The od_kernal() function is
automatically called on a frequent basis by the other OpenDoors
door driver functions, so most often you will not need to be
concerned with this function. However, in order that OpenDoors
can carry out the activities mentioned above with a quick
response, it is important that od_kernal(), or some other
OpenDoors door driver function be called at least once every
second. Thus, if your program will be carrying out some
processing, in which it will not be calling any OpenDoors door
driver functions for more than a second or so, you should call
the od_kernal() function yourself. The example below demonstrates
one method of doing just this.
Note that if for some reason or other, it is not possible for
your program to call the od_kernal() function, or any other
OpenDoors door driver functions for a period of several seconds,
this will not cause your door to crash or fail in any way. The
only problem will be that OpenDoors will not be able to respond
to any action, such as the sysop pressing a function key, or the
user dropping carrier, until such time as you next call
od_kernal(), or some OpenDoors door driver function. Hence, use
of the od_kernal() function will improve the quality and response
time of your program, but calling it or some OpenDoors door
driver function on a regular basis is not absolutely vital.
EXAMPLE As mentioned above, if it is possible that several seconds may
pass between your program calling any OpenDoors door driver
functions, it would be a good idea for you to call the
od_kernal() function on a regular basis. Below is an example of a
door_sleep() function, which will pause for the specified amount
of time, while continually calling the od_kernal() function. This
function will thus allow a door program to pause for a given
length of time, perhaps after having displayed its title screen,
or in order to add special effects to an ANSI animation. In this
case, the program will be able to respond to events such as the
OpenDoors Door Toolkit Manual - Version 4.10 Page 85
sysop pressing function keys, or the user dropping carrier, while
it is pausing.
void door_sleep(int seconds)
{ /* Calculate the timer tick to wait until */
long until=(*(long far *)0x46cL)+(18L*(long)seconds);
/* Loop until the specified number of seconds have expired */
while(until>*(long far *)0x46cL)
{
od_kernal(); /* Repeatedly call od_kernal() */
}
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 86
OD_LIST_FILES()
--------------------------------------------------------------------------------
PURPOSE Lists files in a particular file area (using FILES.BBS)
FORMAT int od_list_files(char *directory);
RETURNS TRUE if successful, FALSE if unsuccessful
DESCRIPTION This function allows you to display a list of files available for
download from a particular file area, as any BBS system would.
The file names and descriptions are taken from the FILES.BBS
located in the directory pointed to by *directory. Thus, to list
the files available for download in C:\APEX\FILES\UPLOADS,
simply:
od_list_files("C:\\APEX\\FILES\\UPLOADS");
OpenDoors uses a third-generation FILES.BBS format, that is
compatible with other FILES.BBS formats, but adds some additional
features. Each line in the FILES.BBS file lists a filename, along
with it's description. Thus, a typical FILES.BBS file might look
as follows:
PKZ110.EXE PKZip file compressor, version 1.10
ODOORS40.LZH The newest version of OpenDoors!
EZVOTE40.ZIP EZVote user voting door.
BID12.ZIP BBS info. door for new BBS users
When displayed, OpenDoors will list the size of each file found
in the FILES.BBS file beside it's name, if the file is found. If
the file does not exist, then a "[OFFLINE]" string is displayed
in the file size column. Title lines may also be added to the
FILES.BBS, by indenting them one or more columns. Thus, you could
have something like:
NEWEST UPLOADS
~~~~~~~~~~~~~~
PKZ110.EXE PKZip file compressor, version 1.10
ODOORS40.LZH The newest version of OpenDoors!
EZVOTE40.ZIP EZVote user voting door.
BID12.ZIP BBS info. door for new BBS users
In addition to this standard FILES.BBS format, OpenDoors will
also permit wildcards to be used in FILES.BBS filenames (ie
FNEWS???.*), or full directory paths to allow files from several
different directories to be included in the same files area.
OpenDoors Door Toolkit Manual - Version 4.10 Page 87
You may alter the colours used to display the various portions of
the files list using the od_control variables:
od_control.od_list_title_col
od_control.od_list_name_col
od_control.od_list_size_col
od_control.od_list_comment_col
od_control.od_list_offline_col
which are documented in the OpenDoors control structure section
on this manual, which begins on page 119.
SEE ALSO od_read_files(), od_write_files(), od_send_file()
OpenDoors Door Toolkit Manual - Version 4.10 Page 88
OD_LOG_OPEN()
--------------------------------------------------------------------------------
PURPOSE Opens a log file and begins logging activities, if logging has
not been disabled.
FORMAT int od_log_open(void);
RETURNS TRUE on success or if logging is disabled
FALSE if unsuccessful
DESCRIPTION This function will cause OpenDoors to open the log file and begin
logging activities, unless logging has been disabled with the
od_logfile_disable variable. The log file name will be taken from
the od_logfile_name variable, which is usually set by the
configuration file. If no logfile name has been set,
od_log_open() will use the logfile named DOOR.LOG. Upon opening
the log file, OpenDoors will write an entry indicating the time
at which the use entered the door.
OpenDoors uses the "FrontDoor format" logfile standard. This was
chosen as it is a clearly documented format that is quickly
becoming the standard for bulletin board software log files. A
segment from a log file produced by OpenDoors is listed below.
---------- Thu 25 Feb 93, EZVote 4.10
> 19:42:23 Brian Pirie entering door
> 19:50:55 User paging system operator
> 19:51:02 Entering sysop chat mode
> 20:05:41 Terminating sysop chat mode
> 20:18:32 User time expired, exiting door
Note that the name of your door to be output to the logfile is
taken from the od_program_name variable. If this variable is not
set, OpenDoors will simply output "OpenDoors x.xx" as the program
name.
If a configuration file is to be used, the od_log_open() function
should be called after calling the od_init_with_config()
function. Thus, the approprate order in which to perform the
various startup operations of your door are:
- Set OpenDoors registration variables
- Set the door's name
- Set default logfile name
- Call od_init_with_config(), if applicable
- Call od_log_open()
After od_log_open() has been called, OpenDoors will automatically
produce logfile entries for the following events:
OpenDoors Door Toolkit Manual - Version 4.10 Page 89
- User paging sysop
- Beginnig of sysop chat
- Ending of sysop chat
- Sysop entering DOS shell
- Sysop returning frmo DOS shell
- User inactivity timeout
- User time expired
- Sysop dropping user back to BBS
- Sysop hanging up on user
- User hagning up on BBS
- Sysop locking out user
- Your door calling the od_exit()
function
These built in log file entries can be customized by altering the
value of the global array od_log_messages. The default definition
for this array is as follows:
char *od_log_messages[12]={"Carrier lost, exiting door",
"System operator terminating call,
exiting door",
"User time expired, exiting door",
"User keyboard inactivity, exiting
door",
"System operator returning user to
BBS, exiting door",
"Exiting door",
"Invoking operating system shell",
"Returning from operating system
shell",
"User paging system operator",
"Entering sysop chat mode",
"Terminating sysop chat mode",
"%s entering door"};
There is no od_log_close() function, as the logfile is
automatically closed when your doors exits through the od_exit()
function.
SEE ALSO od_log_write(), od_init_with_config()
OpenDoors Door Toolkit Manual - Version 4.10 Page 90
OD_LOG_WRITE()
--------------------------------------------------------------------------------
PURPOSE Function to write an entry to the log file
FORMAT int od_log_write(char *message);
RETURNS TRUE on success, or FALSE on failuer
DESCRIPTION This function can be used to write entries to the log file. If
the logfile has not already been opened when you call this
function for the first time, OpenDoors will automatically open
the log file at that time.
To create an entry in the log file, simply call the
od_log_write() function, passing to it the string of the text you
wish to write. You should not include any control characters in
this string, simply the text that should appear on the line.
OpenDoors will automatically format the log file, adding the time
information and other control characters. It is recommended that
the length of the string passed to od_log_write() not exceed 67
characters, in order that logfile lines will all be less than 80
characters in length.
Log file entries do not usually contain periods or other
punctuation at the end of the line. Also, log file entries are
usually written in the present tense. The first character of the
entry is usually upper-case, with all other entries in lower
case. Also, since excessive numbers or lengths of log file
entries can quickly use a lot of disk space, it is best to think
carefully about what events should be recorded in the log file.
It is also a good idea to minimize the number of words used in
the entry, without being too cryptic. As an example, "User
entering options menu" should be used instead of "user entered
the options menu."
SEE ALSO od_log_open()
EXAMPLE Calling the od_log_write() function is as simple as follows:
od_log_write("Awarding user with 5 minutes more time");
OpenDoors Door Toolkit Manual - Version 4.10 Page 91
OD_PAGE()
--------------------------------------------------------------------------------
PURPOSE Function to allow user to page the sysop
FORMAT void od_page(void);
RETURNS N/A
DESCRIPTION This function can be called to allow the user to page the sysop.
This function will ask the user why they wish to chat with the
sysop, and then page the sysop. The sysop will then be free to
break into chat at any time. Sysop paging will also be aborted by
the user, simply by pressing [Enter] when asked for a reason for
chat. When the user pages the sysop, the [Wants-Chat] indicator
will begin to flash on the main status line, and the status line
will switch to show the user's reason for wanting to chat. Also,
the user's total number of pages will be incremented.
Depending upon the setting of the od_control.od_okaytopage
variable, this function will also optionally check sysop paging
hours, and only allow the user to page the sysop during valid
paging hours. For information on the variables containing the
user's total number of pages, the user's want-chat status, valid
sysop paging hours, and the od_control.od_okaytopage variable,
see the section on the OpenDoors control structure, which begins
on page 119.
EXAMPLE For an example of the use of the od_page() function, see the
EZVote example door, which is described beginning on page 25.
OpenDoors Door Toolkit Manual - Version 4.10 Page 92
OD_PRINTF()
--------------------------------------------------------------------------------
PURPOSE Performs formatted output (remote & local)
FORMAT void od_printf(char *format,...);
RETURNS N/A
DESCRIPTION This is one of two OpenDoors function which allows you to display
a string of characters, the other being the od_disp_str()
function. For a complete comparison of the various OpenDoors
display function, see the description of the od_disp_str()
function, on page 46. Like the od_disp_str() function, the
od_printf() function will display its output both on the local
screen, and on the remote user's screen (if the door is not
operating in local mode). However, the od_printf() function also
allows for formatted output, just as the printf() function does.
In addition to providing all of the features of the normal C
printf() function, the od_printf() function allows you to include
codes to change the colour of the display of text. This unique
feature allows you to display multi-coloured text, without having
to use chains of alternating od_disp_str() and od_set_colour()
calls.
As with the printf() function, the od_printf() function accepts
one or more parameters, the first parameter being the format
string to be displayed, and the additional parameters being data
to be displayed within the string. The OpenDoors od_printf()
function recognizes all of the control characters and options
recognized by the normal printf() function. For example, to
display the amount of time that a user has left online, the
following line would be a valid use of the od_printf() function:
od_printf("Time Left: %d\n\r",od_control.user_timelimit);
Note that a full discussion of the printf() function is beyond
the scope of this manual. For more information on using printf(),
please see your Turbo C(++) / Borland C++ manuals.
In addition to the normal control sequences, such as "%s", "%d",
or "%12.12s", the od_printf() function also allows you to include
special colour-setting codes within the format string. These
colour code sequences BEGIN and END with a delimiter character,
which is used to indicate that the sequence is a colour setting.
Consider, for example, the following line of code, which displays
text in various colours:
od_printf("`blue`Blue `green`Green `red`Red \n\r");
OpenDoors Door Toolkit Manual - Version 4.10 Page 93
In this case (assuming of course that a colour monitor is being
used) the word "Blue" will be displayed in the colour blue, the
word "Green" will be displayed in the colour green, and the word
"Red" will be displayed in the colour red. In this case, the
sequence `blue` sets the display colour to dark blue on black.
Here, the the back-quote (`) is the delimiter character which
indicates the beginning and end of the colour sequence. Be sure
not to confuse the back-quote character (`) with the normal
forward quote ('). THIS IS THE MOST COMMON DIFFICULTY EXPERIENCED
WITH THE OD_PRINTF() FUNCTION. The text between the back-quote
characters indicates the colour that should be set. This text can
include the name of the foreground colour, the name of the
background colour, the "bright" keyword and the "flashing"
keyword. The first colour mentioned is taken to be the foreground
colour, and the second the background colour. Case is not
sensitive, additional words can be included for legibility. Thus:
`bright white cyan`
is equivalent to:
`Bright white on a cyan background`.
The "bright" keyword indicates that the foreground colour should
be displayed in high intensity, and the "flashing" keyword
indicates that the text should be flashing. If no background is
specified, the background colour defaults to black. If no
foreground or background colours are specified, the colour
defaults to white on black.
The od_printf() function will automatically detect whether the
user has ANSI or AVATAR graphics, and will send the appropriate
colour codes to change the colour of displayed text. If the user
does not have either ANSI or AVATAR graphics modes turned on,
then the od_printf() function will not send any colour codes.
Thus, a door program using colour codes would work just as well
when ANSI or AVATAR graphics are not available, except that all
text will appear in the same colour.
You may prefer to set colours by using the od_set_colour() or
od_set_attrib() functions, instead of using these cryptic colour
codes imbedded in od_printf() functions. In some cases, however,
it will be much more advantageous to place the colour codes
within your od_printf() strings. As a case in point, consider the
single od_printf() statement in the example, above. To accomplish
the same result using the od_disp_str() and od_set_colour()
functions, you would have to use the following SIX function
calls:
od_set_colour(D_BLUE,D_BLACK);
od_disp_str("Blue ");
od_set_colour(D_GREEN,D_BLACK);
od_disp_str("Green ");
od_set_colour(D_RED,D_BLACK);
od_disp_str("Red \n\r");
OpenDoors Door Toolkit Manual - Version 4.10 Page 94
While this method MAY be easier understand, it certainly requires
many more line of code to accomplish. However, either method will
work, and the choice is up to you as to which method you prefer.
Keep in mind, however, that if the colour to be set is stored in
a variable, instead of always being the same colour, you must use
either the od_set_colour() or od_set_attrib() function to set the
display colour.
While the back-quote (`) character is normally used to delimit a
colour sequence in the od_printf() function, you may wish to be
able to print a back-quote character using the od_printf()
function. In this case, you may configure OpenDoors to use a
different character to represent colour code sequences. To do
this, simply use the od_control.od_colour_delimiter variable,
which is described in the OpenDoors control structure section,
beginning on page 119. For example, if you wished to use the
tilde (~) character instead of the back-quote character to change
colours, simply place the following line within your program, at
some point after having called od_init() or some OpenDoors door
driver function:
od_control.od_colour_delimiter='~';
Also, you may disable the colour code interpretation within the
od_printf() function altogether, by setting the
od_control.od_colour_delimiter variable to 0.
Note that the od_printf() function interprets the colour codes
AFTER parsing the other control sequences, such as "%d" or "%s".
Thus, if you used the command:
od_printf("%s",string);
Any colour codes contained in the string "string" would also be
interpreted. If you did not wish to have any colour code
characters which might be contained in the string "string"
treated as such, you could again disable od_printf()'s colour
code interpretation, by setting the od_control.od_colour_char
variable to 0.
SEE ALSO od_disp_str(), od_disp(), od_putch(), od_repeat(), od_emulate()
EXAMPLE Below is a simple example of a user statistics door program,
which displays various pieces of information to the user, by
using the od_printf() function. Notice the use of colour code
sequences in order to display the titles in a different colour
from the information fields. Note that since the information
available to this door will depend on the BBS system under which
it is running, not all of the information displayed by this door
will be available under all BBS systems. For a description of
what information is available under what BBS systems, see the
OpenDoors control structure portion of this manual, which begins
on page 119.
OpenDoors Door Toolkit Manual - Version 4.10 Page 95
#include "opendoor.h"
int main(int argc,char *argv[])
{
od_init(); /* Begin OpenDoors program */
od_printf("`bright white` YOUR STATISTICS\n\r"); /* Display title */
od_printf("---------------\n\r\n\r");
/* Display statistics */
od_printf("`red`NAME : `blue`%s\n\r",od_control.user_logintime);
od_printf("`red`LOCATION : `blue`%s\n\r",od_control.user_location);
od_printf("`red`PHONE NUMBER : `blue`%s\n\r",od_control.user_homephone);
od_printf("`red`LAST CALL : `blue`%s\n\r",od_control.user_lastdate);
od_printf("`red`NUMBER OF CALLS : `blue`%u\n\r",od_control.user_numcalls);
od_printf("`red`NUMBER OF PAGES : `blue`%u\n\r",od_control.user_numpages);
od_printf("`red`REMAINING TIME : `blue`%d\n\r",od_control.user_timelimit);
od_printf("`red`# OF DOWNLOADS : `blue`%u\n\r",od_control.user_downloads);
od_printf("`red`# OF UPLOADS : `blue`%u\n\r",od_control.user_uploads);
od_printf("`red`KBYTES DL TODAY : `blue`%u\n\r",od_control.user_todayk);
/* Ask user to press [Enter] */
od_printf("`bright green on green`Press [Enter] to return to BBS...\n\r");
while(od_get_key(TRUE)!=13); /* Wait for user to press [Enter] */
od_exit(20,FALSE); /* Return to BBS */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 96
OD_PUTCH()
--------------------------------------------------------------------------------
PURPOSE Function to display a single character.
FORMAT void od_putch(int character);
RETURNS N/A
DESCRIPTION This function performs a similar function to the other OpenDoors
display functions. For information on the uses of the various
OpenDoors display functions, see the description of the
od_disp_str() function, on page 46. This function is most similar
to the od_disp() and od_disp_str() functions, except that it only
displays a single character at a time.
This function will display the character passed to it at the
cursor position in the output window, and then advance the cursor
to the next display position. If OpenDoors is not operating in
local mode, the character will also be sent to the modem, and
thus displayed on the user's screen in the same manner that it is
displayed on the local screen. If either ANSI or AVATAR graphics
mode is activated the character will be displayed in the current
colour.
SEE ALSO od_disp_str(), od_disp(), od_printf(), od_repeat(), od_emulate()
EXAMPLE Below is an example of the use of the od_putch() function. This
example is a function which you could use in place of the
od_get_key() function. This function inputs a single character
from the keyboard, just as the od_get_key() function does.
However, if the character entered is a printable character, the
function will also echo the character to the local screen, using
the od_putch() function. This is helpful for a user to know what
key they have pressed within your door.
char get_key_with_echo(int wait)
{
char pressed=od_get_key(wait); /* Get key from user */
if(pressed>=32 && pressed<=126) /* If key is printable */
{
od_putch(pressed); /* Display the character */
}
return(pressed); /* Return key pressed by user */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 97
For a further example of the user of the od_putch() function, see
the example accompanying the od_repeat() function, which is
described on page 99.
OpenDoors Door Toolkit Manual - Version 4.10 Page 98
OD_REPEAT()
--------------------------------------------------------------------------------
PURPOSE Repeatedly display the specified character any number of times,
using special graphics codes for greater speed, if possible.
FORMAT void od_repeat(char value,unsigned char times);
RETURNS N/A
DESCRIPTION This display function will repeatedly display the character
"value", "times" times. For a complete breakdown of the various
OpenDoors display functions, see the description of the
od_disp_str() function, located on page 46.
The advantage of using this function to display a series of
identical characters is that this function will use special
graphics-mode control sequences to display the repeated character
very efficiently, if the required graphics mode is available. For
example, in AVATAR mode, this function can display an entire line
of one character, by sending a control sequence to the modem that
is only three characters long. If graphics mode is not turned on,
then the od_disp_str() function will simply send the specified
character the appropriate number of times. As with the other
display functions, the output of this function is sent to both
the local and remote screens.
SEE ALSO od_putch(), od_disp_str(), od_disp(), od_printf(), od_emulate()
EXAMPLE The example function below demonstrates the use of the
od_repeat() function in drawing a window (a square box) on the
screen. This function is essentially a simplified version of the
od_draw_box() function, which is described on page 48. Unlike
this function, the od_draw_box() function allows the
customization of the characters used to draw the box's boarder,
and if possible uses additional AVATAR graphics codes to display
the window even faster than this function does. Thus, the
function below is really provided for demonstration purposes
only.
This function accepts four parameters, which indicate the
location of the upper left and lower right corners of the window
to be displayed. The function then displays the window with the
current colour attribute settings. Since this function uses the
od_repeat() function, if AVATAR graphics are available, it can
display the entire window in a fraction of a second, even if it
is displaying a window the size of the entire screen at slow baud
OpenDoors Door Toolkit Manual - Version 4.10 Page 99
rates. Note that this window displaying function requires that
the user has either ANSI or AVATAR graphics mode activated.
void draw_window(char left, char top, char right, char bottom)
{
char line_counter; /* Number of current line being drawn */
char between_size=(right-left)-1; /* X size of window */
od_set_cursor(top,left); /* move to top corner */
od_putch(218); /* display corner character */
od_repeat(196,between_size); /* display top line */
od_putch(191); /* display corner character */
/* loop through middle lines of window */
for(line_counter=top+1;line_counter<bottom;++line_counter)
{
od_set_cursor(line_counter,left); /* move to line start */
od_putch(179); /* display left line char */
od_repeat(' ',between_size); /* display blank area */
od_putch(179); /* display right line char */
}
od_set_cursor(bottom,left); /* move to bottom corner */
od_putch(192); /* display corner character */
od_repeat(196,between_size); /* display bottom line */
od_putch(217); /* display corner character */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 100
OD_SEND_FILE()
--------------------------------------------------------------------------------
PURPOSE Sends an ASCII/ANSI/AVATAR file from the disk, using terminal
emulation. Also interprets RA/QBBS style information control
codes.
FORMAT int od_send_file(char *filename);
RETURNS TRUE if the file was successfully sent
FALSE if OpenDoors was unable to send the file
DESCRIPTION: This powerful function will display any ASCII, ANSI or AVATAR
text file. The od_send_file() function can be used to display
existing BBS text files, such as GOODBYE.A?? before your door
hangs up on the user. You can also make use of the od_send_file()
function to build many of your door screens as external files.
This will allow you to easily create these screens in an ANSI
editor program, such as "TheDraw". It will could also optionally
allow sysops to customize your door for use on their own BBS.
The od_send_file() function is called with the full path and
filename of the file you wish to have displayed. Thus, if you
wished to send the ANSI file MAINMENU.SCR, you would simply call:
od_send_file("MAINMENU.SCR");
In many cases, instead of having just one file that you want
displayed in particular, you will have several different files,
and will want a different one displayed according to the user's
graphics mode. For example, you might have the three files,
MAINMENU.ASC, MAINMENU.ANS and MAINMENU.AVT; the .ASC file
containing no graphics control codes, the .ANS file containing
ANSI graphics control codes, and the .AVT file containing AVATAR
graphics control codes. In this case, you can have the
od_send_file() function automatically select the appropriate file
according to the user's current display mode, by omitting the
extension altogether. Thus, a call to:
od_send_file("MAINMENU");
would cause OpenDoors to automatically send the appropriate file,
according to the user's graphics mode settings. When the
od_send_file() function is used in this "automatic mode" (where
you do not specify a filename extension), it will look for one of
the three filename extensions listed on the following page.
OpenDoors Door Toolkit Manual - Version 4.10 Page 101
+----------------------------------------------------------+
| Extension| File type |
+----------+-----------------------------------------------|
| .ASC | Does not require any graphics mode to display |
| .ANS | Requires ANSI graphics mode to display |
| .AVT | Requires AVATAR graphics mode to display |
+----------------------------------------------------------+
Thus, if the user has AVATAR graphics enabled, od_send_file()
will first search for the .AVT file. If no file exists with the
specified filename and a .AVT extension, od_send_file() will then
search for a .ANS, and if not found .ASC. If the user has only
ANSI graphics enabled, od_send_file() will attempt first to
display the .ANS file, and if not found will search for .ASC. In
the case that the user is using plain-ASCII mode, this function
will attempt only to display the .ASC file.
The od_send_file() will send any ANSI or AVATAR codes in the file
directly to the remote terminal, and interpret them to display on
the sysop's local screen (regardless of the actual filename
extension). This interpretation is accomplished by OpenDoor's
built in terminal emulator. The terminal emulator fully supports
all ANSI and AVATAR level 0 and level 0+ control codes. The
terminal emulator will also translate Apex/Remote Access/QuickBBS
style control codes. The control codes supported by OpenDoors are
listed in the chart on the following pages. When these control
codes are inserted into the file, OpenDoors will replace them
with various pieces of user or system information.
OpenDoors Door Toolkit Manual - Version 4.10 Page 102
+-----------------------------------------------------+
| CONTROL | ASCII | |
| CODE | VALUE | DESCRIPTION |
+---------+-------+-----------------------------------|
| ^FA | 06,65 | Displays the user's full name |
| ^FB | 06,66 | Location the user is calling from |
| ^FC | 06,67 | Displays the user's password |
| ^FD | 06,68 | Business/data phone number |
| ^FE | 06,69 | Home/voice phone number |
| ^FF | 06,70 | Date of the user's last call |
| ^FG | 06,71 | Time of day of the last call |
| ^FH | 06,72 | The user's `A' flags settings |
| ^FI | 06,73 | The user's `B' flags settings |
| ^FJ | 06,74 | The user's `C' flags settings |
| ^FK | 06,75 | The user's `D' flags settings |
| ^FL | 06,76 | User's remaining netmail credit |
| ^FM | 06,77 | Number of messages posted by user |
| ^FN | 06,78 | Last read message number by user |
| ^FO | 06,79 | Displays security level of user |
| ^FP | 06,80 | Number of times user has called |
| ^FQ | 06,81 | Total # of uploads by user |
| ^FR | 06,82 | Total KBytes uploaded by user |
| ^FS | 06,83 | Total # of downloads by user |
| ^FT | 06,84 | Total Kbytes downloaded by user |
| ^FU | 06,85 | # of minute user has used today |
| ^FV | 06,86 | User's screen length setting |
| ^FW | 06,87 | User's first name only |
| ^FX | 06,88 | User's ANSI setting |
| ^FY | 06,89 | User's "continue?" prompt setting |
| ^FZ | 06,90 | Does user have screen clearing on |
| ^F0 | 06,48 | User's Full-screen editor setting |
| ^F1 | 06,49 | User's Quiet mode setting |
| ^F2 | 06,50 | User's hot-keys setting |
| ^F3 | 06,51 | Displays the user's alias |
| ^F4 | 06,52 | The date of the User's first call |
| ^F5 | 06,53 | The user's date of birth |
| ^F6 | 06,54 | User's subscription expiry date |
| ^F7 | 06,55 | Number of days until expiry |
| ^F8 | 06,56 | User's AVATAR setting |
| ^F9 | 06,57 | The user's upload:download ratio |
| ^F: | 06,58 | User's Upload K:download K ratio |
+-----------------------------------------------------+
OpenDoors Door Toolkit Manual - Version 4.10 Page 103
+-----------------------------------------------------+
| CONTROL | ASCII | |
| CODE | VALUE | DESCRIPTION |
+---------+-------+-----------------------------------|
| ^F; | 06,59 | Full-screen message reader |
| ^KA | 11,65 | Total # of calls BBS has received |
| ^KB | 11,66 | Name of the last caller to BBS |
| ^KC | 11,67 | Total # of active messages on BBS |
| ^KD | 11,68 | Displays # of the first message |
| ^KE | 11,69 | Displays # of the last message |
| ^KF | 11,70 | # of times user has paged sysop |
| ^KG | 11,71 | Full name of the current weekday |
| ^KH | 11,72 | Displays total number of users |
| ^KI | 11,73 | Displays the current time |
| ^KJ | 11,74 | Displays the current date |
| ^KK | 11,75 | Minutes the user has been online |
| ^KL | 11,76 | Seconds the user has been online |
| ^KM | 11,77 | Minutes the user has used today |
| ^KN | 11,78 | Seconds the user has used today |
| ^KO | 11,79 | Minutes remaining for user today |
| ^KP | 11,80 | Seconds remaining for user today |
| ^KQ | 11,81 | The user's daily time limit |
| ^KR | 11,82 | Displays the current baud rate |
| ^KS | 11,83 | The current weekday in short-form |
| ^KT | 11,84 | The user's daily download limit |
| ^KU | 11,85 | # of minutes until the next event |
| ^KV | 11,86 | Time of the next system event |
| ^KW | 11,87 | # of node user is currently on |
| ^KX | 11,88 | Disconnects the user |
+-----------------------------------------------------+
SEE ALSO od_emulate(), od_list_files(), od_hotkey_menu()
EXAMPLE For an example of the use of the od_send_file() function in
displaying a custom door menu, see the EZVote example door, which
is described beginning on page 25.
OpenDoors Door Toolkit Manual - Version 4.10 Page 104
OD_SET_ATTRIB()
--------------------------------------------------------------------------------
PURPOSE Function to change the text colour in ANSI or AVATAR mode, using
a single IBM-PC colour attribute value.
FORMAT void od_set_attrib(int colour);
RETURNS N/A
DESCRIPTION od_set_attrib() is one of two functions which change the colour
of the currently displayed text. This function allows you to set
the text colour using a single IBM-PC style colour attribute. On
the other hand, the od_set_colour() function allows you to set
the display colour by specifying a foreground and background text
colour. Generally speaking, which of these two functions you use
will be only a matter of personal preference. You will, however,
most likely find it more convenient to use the od_set_colour()
function for changing display colour. However the od_set_attrib()
offers the advantage of allowing you to manipulate the colour to
be displayed as a single value, instead of two separate values.
This could be convenient, for example, when displaying text in a
user configured colour. Using a single byte to represent the
colour will likely be easier than using two. An alternative
method of setting the colour of displayed text is to include the
colour codes within a string displayed by the od_printf()
function. The benefits of doing this, along with instructions on
how to do this, are described in the section on the od_printf()
function, which begins on page 93.
This function will only have an effect if the user has ANSI or
AVATAR mode turned on. As a result, you can use this function
within your door program, and have your text automatically
displayed in multiple colours if graphics mode is available, and
displayed without colours if graphics mode is not available.
Note that the colour to be set is passed to this function as an
IBM-style screen attribute. Hence, you can set the colour of text
to be displayed by a single hexidecimal value, encoded as
follows:
+------------- Background colour
|
0x7f
|
+------------ Foreground colour
Where the left digit (most significant nibble) of the hexidecimal
number represents the background colour, and the right digit
OpenDoors Door Toolkit Manual - Version 4.10 Page 105
(least significant nibble) represents the foreground colour. Each
of the possible colours, along with their corresponding
hexidecimal values, are listed in the charts, below.
+-----------------------+ +--------------------------+
| Foreground colours | | Background | Flashing |
+-----------------------| +---------------+----------|
| 0 | Black | | 0 | Black | Off |
| 1 | Blue | | 1 | Blue | Off |
| 2 | Green | | 2 | Green | Off |
| 3 | Cyan | | 3 | Cyan | Off |
| 4 | Red | | 4 | Red | Off |
| 5 | Magenta | | 5 | Magenta | Off |
| 6 | Brown | | 6 | Brown | Off |
| 7 | White (grey) | | 7 | White | Off |
| 8 | Bright Black | | 8 | Black | On |
| 9 | Bright Blue | | 9 | Blue | On |
| a | Bright Green | | a | Green | On |
| b | Bright Cyan | | b | Cyan | On |
| c | Bright Red | | c | Red | On |
| d | Bright Magenta | | d | Magenta | On |
| e | Yellow | | e | Brown | On |
| f | White (bright) | | f | White | On |
+-----------------------+ +--------------------------+
Hence, od_set_attrib(0x0e) would set the display colour to yellow
on a black background, and od_set_attrib(0x70) would set the
display colour to black on a while background.
SEE ALSO od_set_colour(), od_emulate(), od_clr_scr(), od_clr_line(),
od_set_cursor()
EXAMPLE At times, you may wish to allow the user to select the colour of
text they wish to have displayed, perhaps to configure your door
for the ideal colours to be displayed on their system. To
demonstrate the use of the od_set_attrib() function, we show
another function, which shows the user all 256 possible colours
that can be displayed, and allows the user to choose which colour
they prefer. The function will then return the colour attribute
value of the user's chosen colour, which can later be passed to
od_set_attrib() to set the displayed text colour to the colour
which was chosen by the user.
unsigned char choose_colour(void)
{
register unsigned char counter; /* for displaying colours */
char string[4]; /* string input by user */
od_set_attrib(0x07); /* display title */
od_disp_str("Available colours:\n\r\n\r");
for(counter=0;counter<=255;) /* loop through all colours */
{
od_set_attrib(counter); /* set appropriate colour */
OpenDoors Door Toolkit Manual - Version 4.10 Page 106
od_printf("%03.3u",counter); /* display colour's number */
if(((++counter)%16)==0) /* after every 16 colours ... */
{
od_set_attrib(0x07); /* ... reset display colour ... */
od_disp_str("\n\r"); /* ... and start a new line */
}
}
od_set_attrib(0x07); /* Allow user to choose colour */
od_disp_str("Which colour do you prefer : ");
od_input_str(string,3,'0','9');
return(atoi(string)); /* Return chosen colour */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 107
OD_SET_COLOUR()
--------------------------------------------------------------------------------
PURPOSE Function to change the text colour in ANSI or AVATAR mode, using
foreground and background colour values.
FORMAT void od_set_colour(int foreground, int background);
RETURNS N/A
DESCRIPTION od_set_colour() is one of two functions which change the colour
of the currently displayed text. This function allows you to set
the text colour using separate foreground an background text
colours, whereas od_set_attrib() allows you to set the text
colour using a single IBM-PC style colour attribute. Generally
speaking, which of these two functions you use is only a matter
of personal preference. An alternative method of setting the
colour of displayed text is to include the colour codes within a
string displayed by the od_printf() function. The benefits of
doing this, along with instructions on how to do this, are
described in the section on the od_printf() function, which
begins on page 93.
This function will only have an effect if the user has ANSI or
AVATAR mode turned on. As a result, you can use this function
within your door program, and have your text automatically
displayed in multiple colours if graphics mode is available, and
displayed without colours if graphics mode is not available.
The od_set_colour() function accepts two parameters, the first
parameter being the foreground colour to be used in displaying
text, and the second parameter being the background colour to be
used in displaying text. For example,
od_set_colour(L_WHITE,D_BLACK);
would set the current colour to Light White on Dark Black. The
foreground and background text colours can be any one of the
colour values listed on the following page.
OpenDoors Door Toolkit Manual - Version 4.10 Page 108
+-------------------+-----------+
| Foreground Colour | Value |
+-------------------+-----------+
| Dark Black | D_BLACK |
| Dark Blue | D_BLUE |
| Dark Green | D_GREEN |
| Dark Cyan | D_CYAN |
| Dark Red | D_RED |
| Dark Magenta | D_MAGENTA |
| Dark Brown | D_BROWN |
| Grey (Dark White) | D_GREY |
| Light Black (Grey)| L_BLACK |
| Light Blue | L_BLUE |
| Light Green | L_GREEN |
| Light Cyan | L_CYAN |
| Light Red | L_RED |
| Light Magenta | L_MAGENTA |
| Yellow | L_YELLOW |
| White | L_WHITE |
+-------------------+-----------+
+-------------------+-----------+
| Background Colour | Value |
+-------------------+-----------+
| Black | D_BLACK |
| Blue | D_BLUE |
| Green | D_GREEN |
| Cyan | D_CYAN |
| Red | D_RED |
| Magenta | D_MAGENTA |
| Brown | D_BROWN |
| Grey | D_GREY |
| Blinking Black | B_BLACK |
| Blinking Blue | B_BLUE |
| Blinking Green | B_GREEN |
| Blinking Cyan | B_CYAN |
| Blinking Red | B_RED |
| Blinking Magenta | B_MAGENTA |
| Blinking Brown | B_BROWN |
| Blinking Grey | B_WHITE |
+-------------------+-----------+
SEE ALSO od_set_attrib(), od_emulate(), od_clr_scr(), od_clr_line(),
od_set_cursor()
EXAMPLE As an example of using the od_set_colour() function to set the
colour of displayed text, we show a pair of two functions. These
functions will allow a program to set the foreground OR
background colour of text, without setting the other. In
contrast, the od_set_colour() function sets both the foreground
and background colour at the same time. These function presume
that they are the only functions used within the door to set the
OpenDoors Door Toolkit Manual - Version 4.10 Page 109
colour of displayed text, and that the original text colour prior
to calling either of these functions is dark white on black.
These function must also have access to the two global variables
"current_foreground" and "current_background", as defined below.
void set_foreground(char foreground);
void set_background(char background);
unsigned char current_foreground=D_BLACK;
unsigned char current_background=D_GREY;
void set_foreground(char foreground)
{ /* set new text colour */
od_set_colour(foreground,current_background);
current_foreground=foreground; /* save new foreground */
}
void set_background(char background)
{ /* set new text colour */
od_set_colour(current_foreground,background);
current_background=background; /* save new background */
}
Using these functions, you would then be able to set just the
foreground text colour by a function call like:
set_foreground(L_YELLOW);
Or set just the background text colour by a function call like:
set_background(D_GREY);
OpenDoors Door Toolkit Manual - Version 4.10 Page 110
OD_SET_CURSOR()
--------------------------------------------------------------------------------
PURPOSE Function to locate the cursor in ANSI or AVATAR mode
FORMAT void od_set_cursor(int row, int col);
RETURNS N/A
DESCRIPTION This function will only have an effect if the user has ANSI or
AVATAR graphics mode turned on. In graphics mode, this function
can be used to position the cursor anywhere on the screen (cursor
is moved both locally and on the remote terminal). The first
parameter "row", can normally have a value between 1 to 23, and
indicates the row, or y position on the screen, where the cursor
should be located. The second parameter, "col", can have a value
between 1 and 80, and indicates the column (x-position) on the
screen, where the cursor should be located.
SEE ALSO od_emulate(), od_clr_scr(), od_clr_line(), od_set_colour(),
od_set_attrib()
EXAMPLE Below is a simple sample door that demonstrates the use of the
od_set_cursor() function. Note that this door detects whether or
not graphics mode is available, and if it is not, will carry out
the same task without the use of the od_set_cursor() function.
#include "opendoor.h"
int main(int argc,char *argv[])
{
od_init(); /* Initialize door operations */
od_clr_scr(); /* Clear the screen */
if(od_control.user_ansi || od_control.user_avatar)
{ /* If graphics mode is available */
od_set_cursor(1,1); /* Display demo */
od_disp_str("Top, Left Corner");
od_set_cursor(1,70);
od_disp_str("Top, Right Corner");
od_set_cursor(15,1);
od_disp_str("Fifteenth line\n\r");
}
else /* If graphics mode is not available */
OpenDoors Door Toolkit Manual - Version 4.10 Page 111
{ /* Display demo */
od_disp_str("Top, Left Corner
Top, Right Corner\n\r");
/* Skip 13 lines */
od_disp_str("\n\n\n\n\n\n\n\n\n\n\n\n\n");
od_disp_str("Fifteenth line\n\r");
}
od_get_key(TRUE); /* Wait for user to press key */
od_exit(FALSE,20); /* Exit door */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 112
OD_SET_STATUSLINE()
--------------------------------------------------------------------------------
PURPOSE To set the currently displayed status line.
FORMAT void od_set_statusline(char setting);
RETURNS N/A
DESCRIPTION If you have the OpenDoors status line enabled within your door
program (as is the default), the sysop will be able to control
the setting of the status line using the F1 - F10 keys on the
keyboard. These function keys are as follows:
[F1] - Display basic door and user information
[F2] - Display phone numbers and important dates
[F3] - Display security flags and up/download info
[F4] - Display system information and current time
[F5] - Display message info and user's settings
[F6] - Display chat reason and sysop's comment
[F9] - Display help information for sysop
[F10] - Turn off the status line
Using the od_set_statusline() function, you can manually set
which of these status line settings is currently selected. The
od_set_statusline() accepts a single parameter, which should be
one of the values listed below, which indicates which status line
you would like to have selected:
+---------------+---------------+-------------------------------+
| | Corresponding | |
| Value | Function Key | Meaning |
+---------------+---------------+-------------------------------+
| STATUS_NORMAL | [F1] | Basic door and user info |
| STATUS_NONE | [F10] | Turn off status line |
| STATUS_HELP | [F9] | Displays help for the sysop |
| STATUS_USER1 | [F2] | Phone Numbers and dates |
| STATUS_USER2 | [F3] | Security flags & up/downloads |
| STATUS_USER3 | [F5] | Message info & user settings |
| STATUS_USER4 | [F6] | Chat reason and sysop comment |
| STATUS_SYSTEM | [F4] | System info & current time |
+---------------+---------------+-------------------------------+
(Note that these keys may be customized using variables in the
OpenDoors control structure.)
Keep in mind that the od_set_statusline() function only
temporarily changes the current status line setting, and that the
sysop will still be able to change the status line to any of the
other settings using the function keys. For instance, if you
OpenDoors Door Toolkit Manual - Version 4.10 Page 113
wished to allow the sysop to normally see all 25 lines of text
displayed by your door, but at the same time to still allow the
sysop to turn on the status line at any time, you could place the
line
od_set_statusline(STATUS_NONE);
at the beginning of your program. Similarly, when the user pages
the sysop, OpenDoors itself calls
od_set_statusline(STATUS_USER4);
in order to display the status line which shows the user's reason
for chat, while still allowing the sysop to switch back to any of
the other status lines.
If you wish to permanently turn off the OpenDoor's status line,
without allowing the sysop to be able to turn it back on using
the sysop function keys, simply set the "od_control.od_status_on"
variable to FALSE. This variable is described in the OpenDoors
control structure section of this manual, which begins on page
119.
OpenDoors Door Toolkit Manual - Version 4.10 Page 114
OD_SPAWN()
--------------------------------------------------------------------------------
PURPOSE To facilitate easy execution of child tasks from doors.
FORMAT int od_spawn(char *command_line);
RETURNS TRUE on success,
FALSE on failure
DESCRIPTION This function allows you to easily run other programs from within
your door programs, such as external file transfer utilities,
compression utilities, and so on.
This function will attempt to swap OpenDoors and your entire door
to expanded memory or disk. OpenDoors swapping can be controlled
by the OpenDoors control structure variables,
od_swapping_disable, od_swapping_ems and od_swap_path. The
od_spawn...() functions first attempt to swap OpenDoors to EMS
memory. If enough EMS 3.2 or later memory is available, it will
be used. If not, OpenDoors will swap to a disk file in the
directory specified by the od_control.od_swap_path variable.
Unlike the other Turbo C(++) / Borland C++ library functions such
as system() or spawnf(), this function will automatically store
the door screen prior to executing the sub-program, and will
restore the screen upon return. This function will also store the
current drive and directory settings prior to executing the
program, and restore them after the program has returned.
Normally, the user's time will continue to be decreased during
the execution of the od_spawn() function. However, you can freeze
the user's time during the spawn process by using the OpenDoors
control structure variable od_spawn_freeze_time.
SEE ALSO od_spawnvpe()
EXAMPLE Below are a few examples of various uses of the od_spawn()
function:
To run the command processor from within your door program, to
allow the sysop access to the DOS shell, simply use the following
line of code:
od_spawn(getenv("COMSPEC"));
OpenDoors Door Toolkit Manual - Version 4.10 Page 115
The following function is an example of using the od_spawn()
function to call DSZ, allowing the user to download a file. You
pass the name of the file that you wish to send to the user. This
function will then ask the user what transfer protocol they would
like to use, generate the appropriate DSZ command line, and then
transmit the file to the user. Note that in order to use a door
which implements this function, the external file transfer
program "DSZ" must be available in the current search path. As an
alternative, you may want to allow the sysop to specify the
location of the DSZ file from within a configuration program. If
you wish to receive a file (allow the user to upload), instead of
sending one, simply change the "s" in the command line to a "r".
char download(char *filename)
{
char commandline[80]; /* string containing DSZ command line */
char protocol; /* character representing chosen protocol */
/* display protocol menu */
od_printf("Select File Transfer Protocol:\n\r");
od_printf(" [X] XModem\n\r");
od_printf(" [Y] YModem\n\r");
od_printf(" [Z] ZModem\n\r");
od_printf("or press [A] to abort transfer\n\r");
do /* loop until valid protocol has been chosen */
{
protocol=od_get_key(); /* get key */
/* abort if [A] key is pressed */
if(protocol=='a' || protocol=='A') return(FALSE);
} while(protocol!='x' && protocol!='y' && protocol!='z' &&
protocol!='X' && protocol!='Y' && protocol!='Z');
od_printf("Begin receiving file now or press [CTRL]-[X] to
abort\n\r");
/* generate DSZ command line */
sprintf(commandline,"dsz port %d s%c %s",
od_control.port+1,
protocol,
filename);
return(od_spawn(commandline)); /* spawn to DSZ */
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 116
OD_SPAWNVPE()
--------------------------------------------------------------------------------
PURPOSE To facilitate easy execution of child tasks from doors. Allows
specification of childs environment, returns errorlevel returned
by child task, and seaches path for the executable file.
FORMAT int od_spawnvpe(int modeflag, char *path, char *argv[],
char *envp[]);
RETURNS -1 on failure
errorlevel returned by child process on success
DESCRIPTION This function behaves very similarly to the od_spawn() function.
Thus, to save space in the manual, I will not recapitulate what
is already said in the description of the od_spawn() function.
Instead, this description concentrates on the additional features
available through the od_spawnvpe() function. If you are not
already familiar with the od_spawn() function, take a moment now
to review the description of that function.
The od_spawn() function (the OpenDoors "quick-spawn" function) is
designed to be quick and easy to use, but does not have all of
the features available in the od_spawnvpe() function. In addition
to the features of the od_spawn() function, the od_spawnvpe()
function also provides the following features:
- od_spawnvpe() will search the "path" for the file
to be executed.
- od_spawnvpe() allows you to pass an altered
environment to the child process.
- od_spawnvpe() returns the errorlevel returned by
the child process.
The parameters passed to the od_spawnvpe() function are identical
to those passed to the C spawnvpe() function. The first paramter
should usually the be P_WAIT flag. The second parameter is the
name of the child program to execute. If a full path to the child
program is not specified, and the child program does not exist in
the current directory, OpenDoors will search the directories
listed by the PATH environment variable. Also, if the .EXE or
.COM extention is not provide, OpenDoors will look forst for a
.COM file, and if not found, for a .EXE file. The third parameter
is an array of arguments to pass to the child process, or NULL if
no arguments are to be passed. The fourth parameter is the
environment to be passed to the child process, or NULL if the a
copy of the current environment should be used.
SEE ALSO od_spawn()
OpenDoors Door Toolkit Manual - Version 4.10 Page 117
EXAMPLE For an example of the use of the od_spawn...() functions, see the
example accompanying the od_spawn() function. As a specific
exampe of the od_spawnvpe function, consider the following code
which executes the "TEST.EXE" program.
od_spawnvpe(P_WAIT,"TEST.EXE",NULL,NULL);
OpenDoors Door Toolkit Manual - Version 4.10 Page 118
--------------------------------------------------------------------------------
CHAPTER 5 - THE OPENDOORS CONTROL STRUCTURE
--------------------------------------------------------------------------------
INTRODUCTION TO THE CONTROL STRUCTURE
--------------------------------------------------------------------------------
The OpenDoors "Control Structure" is used by the OpenDoors door
driver in order to provide you with a wide range of information
about the system on which you door is running, and the user who
is currently using the door, along with providing you a means by
which to customize much of OpenDoor's behaviour. Using the
OpenDoors control structure, you can access or alter information
about the user who is online, information about the system on
which your door is running, and information about OpenDoors
itself. You can also use the control structure to customize all
of the text displayed by OpenDoors, the function keys to which it
responds, and many other aspects of OpenDoor's behaviour.
The OpenDoors control structure is quite simply a normal C
"struct", named od_control, and is defined in the OPENDOOR.H
file. This "struct" contains many different variables, which
provide you access to the information provided by the control
structure. Hence, to access the contents of a control structure
variable, for example the variable "system_name" which contains
the name of the BBS the door is running under, you would use:
od_control.system_name
The following section of this chapter contains a complete
reference to all of the variables which make up the OpenDoors
control structure. This reference includes the name, type and
complete description of the use of each variable. The reference
is divided into the following categories of variables, with the
reference to the variables in each section beginning on the
listed page.
Door Information File Statistics .................121
Modem Settings ...................................124
BBS and Caller Information .......................125
Door Settings ....................................146
OpenDoors Behaviour Customization ................149
Function Keys Customization ......................160
Colour Customization .............................163
Text Customization ...............................164
Within each section, variables are listed alphabetically,
according to their names.
If you would like more information on C "struct"s, please refer
to your Turbo C(++)/Borland C++ manuals.
OpenDoors Door Toolkit Manual - Version 4.10 Page 119
Also, in order to make use of some of the variables in the
OpenDoors control structure, it is important to understand the
concepts of boolean (TRUE/FALSE), and bit-mapped flag variables.
If you are not familiar with these two terms, they are described
in detail in the glossary, located towards the end of this
manual.
OpenDoors Door Toolkit Manual - Version 4.10 Page 120
CONTROL STRUCTURE - DOOR INFO FILE STATS
--------------------------------------------------------------------------------
The following OpenDoors control structure variables provide your
program with information concerning the door information file
from which OpenDoors obtained the BBS and caller information that
is found elsewhere in the control structure. The following
control structure items are listed in this section:
info_path Contains the path to the door
information file
od_info_type Type of door information file that was
found
od_node Node number the door is running under
user_timeofcreation The time at which the door information
file was created
--------------------------------------------------------------------------------
info_path char od_control.info_path[60];
This variable stores the location of the door information file
(such as DORINFO?.DEF, EXITINFO.BBS, CHAIN.TXT, DOOR.SYS,
CALLINFO.BBS, SFDOORS.DAT, etc.), from which OpenDoors will read
and write information about the BBS and the caller online. Note,
however, that this variable only contains the path to this file,
and not the name of the file itself. For example, if your door
knew that the door information file resided in C:\BBS, this
variable might contain "C:\\BBS\\". Remember that when
programming in C, that you must place two backslash characters in
a literal string in order to have a single backslash placed in
the actual string, as shown in the example string above. The
info_path variable is not case sensitive, and may or may not
include the trailing backslash in the directory name.
OpenDoors only uses this variable when it first starts up, during
the od_init() function, and when it shuts down, during the
od_exit() function. Thus, if you wish to alter the setting of the
info_path variable, you must do so before calling od_init(), or
any other OpenDoors functions. Also, you will not normally want
to change the value of this variable after having called
od_init() or any OpenDoors functions, as doing so would cause
OpenDoors to re-write the caller information to another door
information file in a different directory. This would most likely
prevent the BBS system which your door is running under from
being able to re-read the changes to the door information file.
OpenDoors Door Toolkit Manual - Version 4.10 Page 121
It is usually a good idea to design any door in such a way as to
allow the user of the door to specify the location of the door
information file. This will allow the sysop to place your door in
it's own directory, and will facilitate the use of your door on
multi-line BBS systems. If your door has a configuration file,
you may wish to include a setting in the configuration file to
indicate the location of the door information file. However, an
even better design choice would be to allow the location of the
door information file to optionally be passed to the door on the
command line, as the example door, EZVote does. The following
trivial door illustrates a method of reading and setting the
location of the door information file from the door's command
line:
#include "opendoor.h"
main(int argc, char *argv[])
{
if(argc>1) strncpy(od_control.info_path,argv[1],59);
od_disp_str("This is a sample OpenDoors door.\n\r");
od_disp_str("Press any key to continue...\n\r");
od_get_key(TRUE);
od_exit(20);
}
--------------------------------------------------------------------------------
od_info_type char od_control.od_info_type;
This variable indicates the type of information file from which
OpenDoors has obtained the BBS and caller information that is
found elsewhere in the OpenDoors control structure. This variable
will have one of the following values, indicating that the door
information file was of the corresponding type:
+----------------+----------------------------+
| od_info_type | Door Information File Type |
| Value | |
+----------------+----------------------------+
| DORINFO1 | DORINFO?.DEF |
| EXITINFO | EXITINFO.BBS (Normal) |
| RA1EXITINFO | EXITINFO.BBS (Extended) |
| QBBS275EXITINFO| EXITINFO.BBS (QuickBBS) |
| CHAINTXT | CHAIN.TXT |
| SFDOORSDAT | SFDOORS.DAT |
| CALLINFO | CALLINFO.BBS |
| DOORSYS_GAP | DOOR.SYS (GAP/PC-Board) |
| DOORSYS_DRWY | DOOR.SYS (Doorway style) |
| DOORSYS_WILDCAT| DOOR.SYS (WildCat standard)|
| | |
| CUSTOM | Custom door information |
| | file, defined in config |
| | file. |
+----------------+----------------------------+
OpenDoors Door Toolkit Manual - Version 4.10 Page 122
The value of this variable is only valid AFTER od_init() or some
OpenDoors door driver function has been called.
Note that this variable should be treated as a read-only
variable, and should not normally be altered by your program.
Altering this variable may cause OpenDoors to re-write a
different type of door information file upon exiting, than was
read upon startup.
--------------------------------------------------------------------------------
od_node char od_control.od_node;
This variable indicates the node number that the door is running
under. If this information is supplied by the BBS in the door
information file, the node number will be automatically by
OpenDoors. Specifically, the node number can be determined
automatically from systems that produce an SFDOORS.DAT, PC-
Board/GAP style DOOR.SYS or Wildcat style DOOR.SYS door
information file. If this information is not supplied in the door
information file, but is provided by the sysop in the door's
configuration file, OpenDoors will use the value found there.
Alternatively, you can set this variable manually.
On systems that produce a DORINFO?.DEF file, OpenDoors will use
this variable to determine which DORINFO?.DEF file to search for.
For instance, if od_control.od_node is set to 3, OpenDoors will
first search for a DORINFO3.DEF file. If this file is not found,
OpenDoors will then default to the DORINFO1.DEF filename.
--------------------------------------------------------------------------------
user char od_control.user_timeofcreation[6];
_timeof
creation This variable contains the time of day at which the door
information file was created. This variable is available only
when the door is running under a system that produces an
EXITINFO.BBS file. To determine what type of door information
file your door is running under, see the od_control.od_info_type
variable, below.
OpenDoors Door Toolkit Manual - Version 4.10 Page 123
CONTROL STRUCTURE - MODEM SETTINGS
--------------------------------------------------------------------------------
The following OpenDoors control structure items store the
communications settings that OpenDoors uses to communicate with
the modem. These values are normally set upon the first call to
an OpenDoors door driver function, during the od_init()
procedure. However, if you are reading the door information file
yourself, or using the OpenDoors door driver to write some sort
of non-door program, where you have disabled the reading of the
door information file, you will have to set these values yourself
before you use any of the OpenDoors door driver functions.
--------------------------------------------------------------------------------
port char od_control.port;
This variable contains the FOSSIL port number of the modem. Note
that most often, FOSSIL port 0 corresponds to COM1:, FOSSIL port
1 corresponds to COM2:, and so on. This value will normally be
set by the od_init() function, when the door information file is
read, and should not be changed after modem initialization has
been carried out by the od_init() function. In other words,
od_control.port should generally be treated as a read-only
variable.
This variable will most often be useful in passing the port
number to an external program, such as DSZ.
--------------------------------------------------------------------------------
baud unsigned int od_control.baud;
This variable contains the actual BPS rate at which the modem is
operating. Note that if a high speed modem is in use, that the
comm port may actually be locked at a higher baud rate.
OpenDoors Door Toolkit Manual - Version 4.10 Page 124
CONTROL STRUCTURE - BBS AND CALLER INFORMATION
--------------------------------------------------------------------------------
As we have already described, there are two types of variables in
the OpenDoors control structure. Some of the variables are simply
used to allow you to customize OpenDoor's various features, such
as altering colours, prompts, timeouts, etc. Other variables in
the OpenDoors control structure serve to provide you with
information about the user who is online and the BBS system your
door is running under. This section deals with those variables
that provide you with information about the BBS and the user.
The information in these variables is read from the door
information file, a small file created by the BBS specifically
for the purpose of communicating with door programs. Depending on
what BBS system your door is running under, the type of door
information file will vary. Since different door information
files do not all provide the same pieces of information, some
variables in this section will only be available when your door
is running under particular BBS systems. Other variables will be
available with many or all BBS systems. In the description of
each variable in this section, we indicate under which door
information files the particular variable will be . So, if you
wish to access a variable that is only under certain door
information files, your program should test whether or not the
required information is available under the particular door
information file that was found. In order to determine which door
information file your door is running under, you should use the
od_control.od_info_type variable. This variable is described in
the section which begins on page 121. If you test the value of
the od_control.od_info_type variable, and find that the required
information is not available, you may wish to simply use some
sort of default value for the variable, or alternatively, not
allow your door to run under certain BBS systems. Another
possibility, if the required information is not available, is
imply to obtain this information from the user yourself. For
example, if you wished to know the length of the user's screen,
when this information is not available from the door information
file, you could simply prompt the user for their screen length
the first time they use your door. This information could then be
stored in your door's data files for future reference.
As an example of testing what door information file your door is
running under, consider the case where you wanted to display the
user's birthday. The example below will display the user's
birthday if it is known, and otherwise, print the string
"unknown".
if(od_control.od_info_type==RA1EXITINFO)
{
od_disp_str(od_control.user_birthday);
}
else
OpenDoors Door Toolkit Manual - Version 4.10 Page 125
{
od_disp_str("Unknown");
}
The chart below lists the door information file formats that
OpenDoors recognizes, along with example BBS systems that produce
these files and a reference letter for each type. Thus, an
OpenDoors door can run DIRECTLY under ANY BBS SYSTEM that
produces one of these files formats, and under ANY OTHER BBS
system when used in conjunction with a door information file
conversion utility.
+--------------------------+----------------------------------------+
| FILE FORMAT | EXAMPLE BBS SYSTEMS |
+--------------------------+----------------------------------------+
| CHAIN.TXT | WWIV |
+--------------------------+----------------------------------------+
| DORINFO1.DEF | RBBS-PC |
+--------------------------+----------------------------------------+
| DORINFO1.DEF | QuickBBS |
| & | Remote Access (versions 0.01-0.04) |
| EXITINFO.BBS (Std. Ver.) | |
+--------------------------+----------------------------------------+
| DOOR.SYS (DoorWay Style) | Remote Access |
+--------------------------+----------------------------------------+
| DOOR.SYS (PCB/GAP Style) | PC-Board |
| | GAP |
+--------------------------+----------------------------------------+
| DOOR.SYS (WildCat Style) | Wildcat 3.00 and above |
| | Telegard |
+--------------------------+----------------------------------------+
| SFDOORS.DAT | Spitfire |
| | TriTel |
+--------------------------+----------------------------------------+
| CALLINFO.BBS | WildCat 2.xx |
+--------------------------+----------------------------------------+
| DORINFO1.DEF | Remote Access (versions 1.00 and later)|
| & | |
| EXITINFO.BBS (Ext. Ver.) | |
+--------------------------+----------------------------------------+
OpenDoors Door Toolkit Manual - Version 4.10 Page 126
The following chart lists all of the OpenDoors control structure
variables in this section, along with a brief description of
their use. The variables are then described in detail, below.
+-----------------------+-----------------------------------------------+
| VARIABLE NAME | VARIABLE CONTENTS |
+-----------------------+-----------------------------------------------+
| EMSI INFORMATION | Information on current IEMSI session |
| event_status | The status of the next system event |
| event_starttime | The start time of the next system event |
| event_errorlevel | The errorlevel of the next system event |
| event_days | The days of the week to execute the event |
| event_force | Whether the next system event is forced |
| event_last_run | When the next system event was last run |
| sysop_name | The name of the BBS's sysop |
| system_calls | Total number of calls BBS has received |
| system_last_caller | The name of the last caller to the BBS |
| system_name | The name of the BBS |
| TIMELOG VARIABLES | The times at which the BBS has been most busy |
| user_ansi | Whether the user has ANSI graphics mode on |
| user_attribute | User attribute bit-mapped flags |
| user_attrib2 | Second set of user attribute bit-mapped flags |
| user_avatar | Whether the user has AVATAR graphics mode on |
| user_birthday | The date the user was born |
| user_callsign | The user's amateur radio call sign |
| user_combinedrecord | The user's combined message areas settings |
| user_comment | Sysop's comment about the user |
| user_credit | Amount of NetMail credit the user has |
| user_dataphone | The user's data phone number |
| user_date_format | Format user wishes to have dates displayed in |
| user_deducted_time | Total time that has been subtracted from user |
| user_downk | Total Kilobytes downloaded by the user |
| user_downlimit | User's daily download limit |
| user_downloads | Total number of files downloaded by the user |
| user_echomailentered | Whether or not the user has entered EchoMail |
| user_error_free | Whether or not connection is error-free |
| user_file_area | The user's current file area |
| user_firstcall | Date of the user's first call to the BBS |
| user_flags | User's sysop-defined flag settings |
| user_forward_to | Name to forward user's mail to |
| user_group | User's group number |
| user_handle | User's alias |
| user_homephone | User's home telephone number |
| user_language | User's language setting |
| user_last_pwdchange | Total calls since last password change |
| user_lastdate | Date of the user's last call |
| user_lastread | Highest message number read by user |
| user_lasttime | Time of the user's last call |
| user_location | Name of the city where the user lives |
| user_logindate | Date on which the current call began |
| user_loginsec | User's security at the beginning of this call |
+-----------------------+-----------------------------------------------+
OpenDoors Door Toolkit Manual - Version 4.10 Page 127
+-----------------------+-----------------------------------------------+
| VARIABLE NAME | VARIABLE CONTENTS |
+-----------------------+-----------------------------------------------+
| user_logintime | Time at which the current call began |
| user_logonpassword | User's password at the beginning of this call |
| user_menustack | Contents of the user's current menu stack |
| user_menustackpointer | Pointer to the top of the menu stack |
| user_messages | Total number of messages written by the user |
| user_msg_area | The user's current message area |
| user_name | The user's name |
| user_net_credit | The user's remaining netmail credit |
| user_netmailentered | Whether or not the user has entered NetMail |
| user_num | The user's record number in the user file |
| user_numcalls | Number of calls the user has made to the BBS |
| user_numpages | Number of times the user has paged the sysop |
| user_password | The user's current password |
| user_pending | The value of unsent NetMail written by user |
| user_reasonforchat | The reason the user wishes to chat with sysop |
| user_screen_length | The length of the user's screen |
| user_screenwidth | The width of the user's screen |
| user_security | The user's security access level |
| user_sex | The user's gender |
| user_subdate | The date the user's subscription expires |
| user_timelimit | The user's daily time limit |
| user_todayk | Kilobytes downloaded by the user today |
| user_upk | Total Kilobytes uploaded by the user |
| user_uploads | Total number of files uplaoded by the user |
| user_wantchat | Whether or not the user wishes to chat |
| user_xi_record | The user's record in the USERSXI.BBS file |
+-----------------------+-----------------------------------------------+
--------------------------------------------------------------------------------
EMSI char od_control.ra_emsi_session;
INFORMATION char od_control.ra_emsi_crtdef[41];
char od_control.ra_emsi_protocols[41];
char od_control.ra_emsi_capabilities[41];
char od_control.ra_emsi_requests[41];
char od_control.ra_emsi_software[41];
char od_control.ra_hold_attr1;
char od_control.ra_hold_attr2;
char od_control.ra_hold_len;
These variables provide your door with information pertaining to
an interactive EMSI session that has been established. Note that
these variables are only available under systems that produce an
RA 1.00 and later style extended EXITINFO.BBS door information
file.
OpenDoors Door Toolkit Manual - Version 4.10 Page 128
If an IEMSI session has been established, the boolean variable
od_control.ra_emsi_session will be TRUE, and if no session has
not been established, this variable will be FALSE.
A full discussion of the IEMSI protocol is beyond the scope of
this manual. Specifications for the IEMSI protocol are available
from the OpenDoors support BBS.
--------------------------------------------------------------------------------
event_days unsigned char od_control.event_days;
This variable is a bit-mapped flag of the days of the week on
which the next system event is run. The bit-map bits are as
follows:
+-----+------+-----------+
| BIT | MASK | MEANING |
+-----+------+-----------+
| 0 | 0x01 | Sunday |
| 1 | 0x02 | Monday |
| 2 | 0x04 | Tuesday |
| 3 | 0x08 | Wednesday |
| 4 | 0x10 | Thursday |
| 5 | 0x20 | Friday |
| 6 | 0x40 | Saturday |
| 7 | 0x80 | All Days |
+-----+------+-----------+
For more information on bit-mapped flags, see the glossary item
entitled "BIT-MAPPED FLAGS".
This variable is only available under systems that produce an
EXITINFO.BBS door information file.
--------------------------------------------------------------------------------
event_ unsigned char od_control.event_errorlevel;
errorlevel
This variable contains the ErrorLevel associated with the next
system event. This variable is only available under systems that
produce an EXITINFO.BBS door information file.
--------------------------------------------------------------------------------
event char od_control.event_force;
_force
This variable indicates whether the next system event should be
forced to run at a particular time. If this variable contains a
value of TRUE, then the user should be forced off-line in order
to accommodate the event, and if this variable is false, then the
event can wait until after the user logs off normally. This
OpenDoors Door Toolkit Manual - Version 4.10 Page 129
variable is only available under systems that produce an
EXITINFO.BBS file.
--------------------------------------------------------------------------------
event char od_control.event_last_run[9];
_last_run
This variable contains a string representing the date on which
the next system event was last run, and is in the same format as
the user_lastdate variable. This variable is only available under
systems that produce an EXITINFO.BBS file.
--------------------------------------------------------------------------------
event char od_control.event_starttime[6];
_starttime
This variable contains a string representing the time at which
the next system event is scheduled to start, in the same format
as the user_lasttime variable. This variable is only available
under systems that produce an EXITINFO.BBS or Wildcat style
DOOR.SYS door information file.
--------------------------------------------------------------------------------
event unsigned char od_control.event_status;
_status
This variable represents the status of the next system event, and
will be equal to the value
ES_ENABLED
if and only if the other event information contained in the
control structure is valid. This variable is only available under
systems that produce an EXITINFO.BBS file.
--------------------------------------------------------------------------------
sysop_name char od_control.sysop_name[40];
The od_control.sysop_name variable contains the name of the sysop
of the BBS under which your door is running. This variable is
available under any BBS system that produces a DORINFO?.DEF
(including RA & QBBS which process both DORINFO1.DEF and
EXITINFO.BBS files), or Wildcat style DOOR.SYS file.
--------------------------------------------------------------------------------
system_calls long od_control.system_calls;
OpenDoors Door Toolkit Manual - Version 4.10 Page 130
This variable contains the total number of calls that have been
placed to the BBS, and is available under any BBS which produces
an EXITINFO.BBS file.
--------------------------------------------------------------------------------
system_last char od_control.system_last_caller[36];
_caller
This string contains the name of the previous caller to the BBS,
on any line, and is available under EXITINFO.BBS.
--------------------------------------------------------------------------------
system_name char od_control.system_name[40];
The od_control.system_name variable contains the name of the BBS
under which your door is running. This variable is available
under any BBS system that produces a DORINFO?.DEF (including RA &
QBBS which process both DORINFO1.DEF and EXITINFO.BBS files).
--------------------------------------------------------------------------------
TIMELOG char od_control.timelog_start_date[9];
VARIABLES
This string contains the date of the beginning of the time period
for which the time log is recorded. This variable is available
under any system that produces an EXITINFO.BBS file.
int od_control.timelog_busyperhour[24];
This variable is an array of 24 elements, with each element
indicating the total number of times the BBS was in use during
each of the 24 hours of the day. Element 0 corresponds to the
time period of 0:00-1:00, element 1 corresponds to the time
period of 1:00-2:00, and so on. In order to determine the
frequency of system use during any hour as a percentage, simply
calculate the total of all 24 entries in the array, and divide
any given entry by the total, in order to come up with an
average. This variable is available under any system that
produces an EXITINFO.BBS file.
int od_control.timelog_busyperday[7];
This variable is an array of 7 elements, with each element
indicating the total number of times the BBS was in use during
each of the 7 days of the week. Here, elements 0 corresponds to
Sunday, element 1 to Monday, and so on. In order to calculate the
frequency of system use during any day of the week, use the same
method as for calculating the frequency of calls during each
hour, as described above. This is only available under systems
that produces an EXITINFO.BBS file. Note that at least some, if
OpenDoors Door Toolkit Manual - Version 4.10 Page 131
not all, versions of RemoteAccess do not maintain this variable
correctly, and thus even with the presence of an EXITINFO.BBS
file, this array may contain all zero entries.
--------------------------------------------------------------------------------
user_ansi char od_control.user_ansi;
This variable contains a boolean value, indicating whether or not
the user has ANSI mode turned on. If ANSI graphics mode is
enabled, this variable will contain a value of TRUE, and if ANSI
graphics mode is disabled, this variable will contain a value of
FALSE. Many of the OpenDoors door driver functions test the
setting of this variable in order to determine whether or not
they should send ANSI-graphics control characters. Also, if this
variable contains a TRUE value, OpenDoors will display an
"[ANSI]" indicator on the status line.
You may change the value of this variable at any time after the
first call to od_init() or any other OpenDoors door driver
functions. Depending upon what BBS system your door is running
under, changes to this variable may or may not result in changes
to the user's ANSI setting upon return to the BBS.
This variable is available under all door information file
formats.
--------------------------------------------------------------------------------
user_ unsigned char od_control.user_attribute;
attribute
This variable is a bitmap of eight flags, each of which represent
individual pieces of information pertaining to the user that is
currently online. These flags are as follows:
+-----+------+-----------------------+
| BIT | MASK | DESCRIPTION |
+-----+------+-----------------------+
| 0 | 0x01 | Is the user deleted |
| 1 | 0x02 | Is screen clearing on |
| 2 | 0x04 | Is "more" prompt on |
| 3 | 0x08 | Is ANSI mode on |
| 4 | 0x10 | User no-kill setting |
| 5 | 0x20 | Transfer-priority |
| 6 | 0x40 | Full screen editor |
| 7 | 0x80 | Quiet mode |
+-----+------+-----------------------+
For more information on using and setting bit-mapped flags,
please see the entry entitled "BITMAPED FLAGS" in the glossary of
this manual.
Note that this variable is only available under systems that
produce and EXITINFO.BBS format door information file.
OpenDoors Door Toolkit Manual - Version 4.10 Page 132
--------------------------------------------------------------------------------
user_ unsigned char od_control.user_attrib2;
attrib2
See the user_attrib variable for more information. This variable
is like the user_attrib variable, except that it contains
different information. The bit-mapped flags for the
od_control.user_attrib2 variable are as follows:
+-----+------+-----------------------+
| BIT | MASK | DESCRIPTION |
+-----+------+-----------------------+
| 0 | 0x01 | User hot-keys setting |
| 1 | 0x02 | Is AVATAR graphics on |
| 2 | 0x04 | Full screen reader |
| 3 | 0x08 | Hidden from userlist |
+-----+------+-----------------------+
Note that this variable is only available under systems that
produce an EXITINFO.BBS door information file.
--------------------------------------------------------------------------------
user_avatar char od_control.user_avatar;
This variable is a boolean value indicating whether or not AVATAR
graphics mode is on. If AVATAR graphics is available, then many
of the OpenDoors door driver functions will make use of AVATAR
graphics codes for greater display speed. If AVATAR graphics mode
is on, a [AVT] indicator will appear on the status line. If your
door is running under a system which produces an RA 1.00+ style
extended EXITINFO.BBS door information file, the user_avatar
variable is set automatically. If the extended EXITINFO.BBS file
is not available, this value will default to FALSE. In this case,
you may wish to ask the user whether or not they wish to use
AVATAR graphics, and thus set this variable yourself.
--------------------------------------------------------------------------------
user char od_control.user_birthday[9];
_birthday
This variable is a string, in the same format as the
od_control.user_lastcall variable, which stores the date of the
user's birthday, if it is available. This variable is only
available under systems that produce an RA 1.00 and later style
extended EXITINFO.BBS or Wildcat style DOOR.SYS file.
--------------------------------------------------------------------------------
user char od_control.user_callsign[12];
_callsign
OpenDoors Door Toolkit Manual - Version 4.10 Page 133
This variable is a string which contains the user's amateur radio
call sign, if any. This variable is only available under systems
that produce a CHAIN.TXT file.
--------------------------------------------------------------------------------
user_combined unsigned char od_control.user_combinedrecord[25];
record
This variable is an array of bit-mapped flags, with each flag
corresponding to an individual message area. In this case, the
first bit of od_control.ra_combinedrecord[0] corresponds to the
first message area, the second bit to the second message area,
and so on. If any given bit-flag is turned on, then the user has
corresponding message area enabled for combined access, and if
the bit is turned off, the user does not have the area enabled
for combined access. A detailed description of the combined
message access is beyond the scope of this manual. This variable
is only available under systems that produce an RA 1.00 or later
style extended EXITINFO.BBS door information file.
--------------------------------------------------------------------------------
user_comment char od_control.user_comment[81];
This variable is a string which contains the sysop's comment
about the user that is currently online. This comment may be
displayed on the OpenDoors status line, if this variable is
available. This variable is available under systems that produce
an RA 1.00 and later style extended EXITINFO.BBS or Wildcat style
DOOR.SYS file.
--------------------------------------------------------------------------------
user_credit unsigned int od_control.user_credit;
This variable contains the total amount of NetMail credit that
the caller has left. Changes to this variable will be by the BBS
when your door exits and control is returned to the BBS. This
variable is only available under systems that produce an
EXITINFO.BBS door information file.
--------------------------------------------------------------------------------
user_ char od_control.user_dataphone[13];
dataphone
This string contains the user's data or business phone number, if
available. This value is only available under system that produce
EXITINFO.BBS, PC-Board/GAP style DOOR.SYS and WildCat DOOR.SYS
format door information files.
OpenDoors Door Toolkit Manual - Version 4.10 Page 134
--------------------------------------------------------------------------------
user int od_control.user_deducted_time;
_deducted
_time This variable contains a signed integer value, which indicates
the total amount of time that has been decuted from the user
during this call. This variable is only available under systems
that produce an RA 1.00 and later style extended EXITINFO.BBS
door information file.
--------------------------------------------------------------------------------
user_downk unsigned int od_control.user_downk;
This variable contains the total kilobytes of files that the
current user has downloaded from the BBS, and is available under
systems that produce EXITINFO.BBS, Wildcat style DOOR.SYS or
SFDOORS.DAT format door information files.
--------------------------------------------------------------------------------
user unsigned int od_control.user_downlimit;
_downlimit
This variable contains the total number of kilobytes that the
caller is permitted to download during this call. If your door
allows files do be downloaded, you will probably want to compare
the value of this variable to the size of any file to be
transferred and the total kilobytes already downloaded, as stored
in the od_control.user_todayk variable. This variable is only
available under systems that produce an EXITINFO.BBS file.
--------------------------------------------------------------------------------
user unsigned int od_control.user_downloads;
_downloads
This variable contains the total number of files that the current
user has downloaded from the BBS, and is available under systems
that produce EXITINFO.BBS, PC-Board/GAP style DOOR.SYS, WildCat
style DOOR.SYS or SFDOORS.DAT format door information files.
--------------------------------------------------------------------------------
user_echo char od_control.user_echomailentered;
mailentered
This variable is a boolean value, indicating whether or not the
user has entered new EchoMail during this call. If this variable
has a value of TRUE, then EchoMail has been entered, and if it
has a value of FALSE, then EchoMail has not been entered. This
variable will contain a valid value only after od_init() or some
OpenDoors door driver function has been called. Any changes made
to this variable will be reflected within the BBS software when
control is returned to the BBS. This variable is accessible only
OpenDoors Door Toolkit Manual - Version 4.10 Page 135
under systems which produce an EXITINFO.BBS door information
file.
--------------------------------------------------------------------------------
user_error char od_control.user_error_free;
_free
This variable contains a boolean value indicating whether or not
the user is connected to the BBS via an error free connection
(eg. a V.42/MNP or similar modem protocol). This variable is only
available under systems that produce an SFDOORS.DAT, Wildcat
style DOOR.SYS or RA 1.00 or later style extended EXITINFO.BBS
door information file.
--------------------------------------------------------------------------------
user_first char od_control.user_firstcall[9];
call
This variable is a string which contains the date of the user's
first call, in the same format as the od_control. user_lastcall
variable. This variable is only available under systems which
produce an RA 1.00 and later style extended EXITINFO.BBS door
information file.
--------------------------------------------------------------------------------
user_ unsigned char od_control.user_flags[4];
flags
The od_control.user_flags variable is an array of four sysop
defined bit-mapped flags, which represent some sort of
information about the user. od_control.user_flags[0] stores flags
A1 - A8 in bits 0 through 7, respectively. Likewise,
od_control.user_flags[1] stores flags B1 - B8, and so on. This
variable is only available under systems that produce
EXITINFO.BBS format door information files.
--------------------------------------------------------------------------------
user_handle char od_control.user_handle[36];
This variable contains the user's alias or handle name, if any.
If the user does not have and alias or handle, this variable will
be blank. This variable is only available under systems that
produce a CHAIN.TXT, RA 1.00 and later extended EXITINFO.BBS or
Wildcat style DOOR.SYS door information file.
--------------------------------------------------------------------------------
user_ char od_control.user_homephone[13];
homephone
OpenDoors Door Toolkit Manual - Version 4.10 Page 136
This string contains the user's home or data phone number, if
available. This value is only available under system that produce
one of the following door information files: EXITINFO.BBS, PC-
Board/GAP style DOOR.SYS, WildCat style DOOR.SYS or SFDOORS.DAT.
--------------------------------------------------------------------------------
user unsigned char od_control.user_last_pwdchange;
_last
_pwdchange This variable contains the number of calls that the user has
made since they last changed their password. This variable is
only available under EXITINFO.BBS files.
--------------------------------------------------------------------------------
user char od_control.user_lastdate[9];
_lastdate
This variable is a string containing the date of the user's last
call to the BBS, and should always be of the format:
"MM-DD-YY"
Where MM is two digits representing the number of the month of
the user's call, with 1 being January, 2 being February, and so
on. DD should be two digits representing the day of the month of
the user's last call, beginning with 1, and MM should be the last
two digits of the year of the user's last call.
This variable is only available under systems that produce one of
the following door information files: CHAIN.TXT, EXITINFO.BBS,
PC-Board/GAP style DOOR.SYS or WildCat style DOOR.SYS files.
--------------------------------------------------------------------------------
user_ unsigned int od_control.user_lastread;
lastread
This variable contains the number of the highest message number
that the user has read, and is only available under EXITINFO.BBS
format door information files.
--------------------------------------------------------------------------------
user char od_control.user_lasttime[6];
_lasttime
This variable contains a string representing the time of the
user's last call to the BBS, and should always be of the format:
"HH:MM"
Where HH is two digits representing the 24-hour format hour of
the user's last call, and MM is two digits representing the
OpenDoors Door Toolkit Manual - Version 4.10 Page 137
minute of the user's last call. Thus, the following strings would
be valid entries for this string:
"00:01" (12:01 am)
"03:47" (3:47 am)
"18:20" (6:20 pm)
This variable is only available under systems that produce an
EXITINFO.BBS or Wildcat style DOOR.SYS format door information
file.
--------------------------------------------------------------------------------
user char od_control.user_location[26];
_location
This string contains the name of the location from which the
current user is calling from. This will usually be the name of
the city, region (province, state, etc.) and sometimes country
where the user lives. The contents of this variable are displayed
on the OpenDoors status line. The value of this variable is valid
after od_init() or any other OpenDoors door driver function has
been called. Also, you may change the value of this variable if
you wish. However, not that these changes may not immediately be
reflected in the status line, and may or may not cause the
setting to be changed after the user returns to the BBS. This
variable is available under systems that produce one of the
following door information files: DORINFO?.DEF, EXITINFO.BBS, PC-
Board/GAP style DOOR.SYS, WildCat style DOOR.SYS SFDOORS.DAT and
CALLINFO.BBS, but is not available under CHAIN.TXT or DoorWay
style DOOR.SYS files.
--------------------------------------------------------------------------------
user char od_control.caller_logindate[9];
_logindate
This variable contains a string representing the date on which
the current call to the BBS began. This variable is in the same
format as the od_control.user_lastdate variable, described below.
This variable is only available under systems which produce an
EXITINFO.BBS file.
--------------------------------------------------------------------------------
user long od_control.user_loginsec;
_loginsec
This variable contains the user's security at login, and can be
used to detect changes by the sysop or other programs during the
course of the call, by comparing it's value with the
od_control.user_security variable. This variable is only
available under systems which produce an EXITINFO.BBS file.
OpenDoors Door Toolkit Manual - Version 4.10 Page 138
--------------------------------------------------------------------------------
user char od_control.user_logintime[6];
_logintime
This variable contains a string representing the time of day at
which the current call to the BBS began. This variable is in the
same format as the od_control.user_lasttime variable, which is
also described below. This variable is available under systems
which produce an EXITINFO.BBS, a Wildcat style DOOR.SYS, or an
SFDOORS.DAT file.
--------------------------------------------------------------------------------
user char od_control.user_logonpassword[16];
_logon
password This variable is a string which contains the user's password
at the time at which the current call to the BBS began. This
variable can be used to detect changes by the sysop or other
programs to the user's password, which have taken place during
the course of the call. In order to detect such changes, simply
compare the contents of this string with the contents of the
od_control.user_password variable. This variable is only
available under systems which produce an EXITINFO.BBS format door
information file.
--------------------------------------------------------------------------------
user char od_control.user_menustack[50][9];
_menustack
This variable is an array of 50 strings, containing the stack of
BBS menus that have been executed, and is used to record the
current position of the user within the BBS's menu system. Each
string contains just the base portion of the filename of the
menu, without the extension. The od_control.ra_menustackpointer
variable points to the top of the menu stack. However, a complete
discussion of the menu stack is beyond the scope of this manual.
This variable is only available under systems that produce an RA
1.00 and later style extended EXITINFO.BBS door information file.
--------------------------------------------------------------------------------
user unsigned char od_control.user_menustackpointer;
_menustack
pointer This variable points to the top of the current menu stack. For
more information on the menu stack, please refer to the
od_control.ra_menustack variable, above. This variable is only
available under systems that produce an RA 1.00 and later style
extended EXITINFO.BBS door information file.
--------------------------------------------------------------------------------
user unsigned int od_control.user_messages;
_messages
OpenDoors Door Toolkit Manual - Version 4.10 Page 139
This variable contains a value representing the total number of
messages that have been written by the user, and is available
under EXITINFO.BBS or Wildcat style DOOR.SYS format door
information files.
--------------------------------------------------------------------------------
user_name char od_control.user_name[36];
This string contains the name of the user that is currently on-
line, and is used by OpenDoors to display the current user name
on the status line, and will most likely be used by your door for
differentiating among different users. In most cases, you should
probably not change the value of this variable, as a user's name
does not usually change, and doing so could results in problems
when returning to some BBS systems. For an example of using this
variable, see the EZVote example program. This variable is
available under all BBS systems.
--------------------------------------------------------------------------------
user_net_ unsigned int od_control.user_net_credit;
credit
This variable contains the amount of NetMail credit that the
current user has to his or her name. This variable is only
available under systems that produce an EXITINFO.BBS file.
Note that if you wish to change the value of the user's remaining
NetMail credit, you should use the od_control. user_credit
variable, instead of this variable.
--------------------------------------------------------------------------------
user_net char od_control.user_netmailentered;
mailentered
This variable is a boolean value, indicating whether or not the
user has entered new NetMail or GroupMail during this call. If
this variable has a value of TRUE, then NetMail/GroupMail has
been entered, and if it has a value of FALSE, then
NetMail/GroupMail has not been entered. This variable will
contain a valid value only after od_init() or some OpenDoors door
driver function has been called. Any changes made to this
variable will be reflected within the BBS software when control
is returned to the BBS. This variable is accessible only under
systems which produce an EXITINFO.BBS door information file.
--------------------------------------------------------------------------------
user_num unsigned int od_control.user_num;
This variable contains the number of the user's record in the
user database file, where 0 is the first record. This can be
OpenDoors Door Toolkit Manual - Version 4.10 Page 140
useful for changing user settings that are not re-read by the
BBS, such as the user's phone number or security level which
might be altered by a call back verification door. However, the
value of this variable itself should not be altered.
This variable is available under systems which produce any of the
following door information file formats: CHAIN.TXT, PC-Board/GAP
style DOOR.SYS, Wildcat style DOOR.SYS SFDOORS.DAT and
EXITINFO.BBS.
--------------------------------------------------------------------------------
user_ unsigned int od_control.user_numcalls;
numcalls
This variable contains the total number of calls that the current
user has placed to the BBS, and is available under systems that
produce EXITINFO.BBS or PC-Board/GAP and Wildcat style DOOR.SYS
door information files.
--------------------------------------------------------------------------------
user unsigned int od_control.user_numpages;
_numpages
The value of this variable contains the total number of times
that the user has paged the sysop, and can be used to limit the
number of times that the user is permitted to page the sysop.
OpenDoors increments this variable every time that the user pages
the sysop, via the od_page() function. This variable is used with
all types of door information files. However, this variable will
only reflect the value within the BBS if an EXITINFO.BBS file is
produced. Otherwise, the variable will only contain the number of
times that the user has paged within the door, but not the total
number of times the user has paged. Under EXITINFO.BBS systems,
changes to the value of this variable will be reflected within
the BBS upon return by the DOOR.
--------------------------------------------------------------------------------
user char od_control.user_password[16];
_password
This variable contains the user's password for accessing the BBS.
OpenDoors does not use this value itself. This variable will
contain a valid value only after od_init() or some OpenDoors door
driver function has been called. You may change the value of this
variable. Note, however, that changes in this variable may or may
not cause the setting to be changed when control returns to the
BBS - this will depend upon the particular BBS system your door
is running under. This variable is only available under systems
that produce one of the following door information files:
EXITINFO.BBS, PC-Board/GAP and Wildcat style DOOR.SYS,
SFDOORS.DAT, and CALLINFO.BBS.
OpenDoors Door Toolkit Manual - Version 4.10 Page 141
--------------------------------------------------------------------------------
user_pending unsigned int od_control.user_pending;
This variable represents the total value of NetMail that has been
written by the current user, but not yet exported from the
message base. This variable is only available under systems that
produce an EXITINFO.BBS door information file.
--------------------------------------------------------------------------------
user_reason char od_control.user_reasonforchat[78];
forchat
This variable is a string, containing the reason for which the
user wishes to chat with the sysop, as they entered at the time
of paging the sysop. This variable will contain an empty string
if the user has not paged the sysop, or if the reason the user
wishes to chat is unknown. See also the od_control.user_wantchat
variable. This variable is available under all BBS systems,
regardless of what style of door information file they produce.
However, this variable will not be passed between the door and
BBS, and thus the user's reason for chat within the door will not
necessarily correspond to their reason for chat outside the door.
--------------------------------------------------------------------------------
user unsigned int od_control.user_screen_length;
_screen
_length This value of this variable represents the total number of
lines that can be displayed on the user's screen at once, and is
usually either 24 or 25. You may wish to make use of this
variable to allow your door to pause the display of long pieces
of text after every screen length, in order to allow the user to
read this information before it passes off of their screen. In
this case, you would simply maintain a counter of the total
number of lines displayed, and when this value reaches one less
than the length of the user screen, display a prompt asking the
user to whether or not they wish to continue.
This variable is set to the user's setting within the BBS under
systems that produce any of the following door information file
formats: CHAIN.TXT, EXITINFO.BBS, PC-Board/GAP and Wildcat style
DOOR.SYS and CALLINFO.BBS files.
This variable is used by the OpenDoors door driver function,
od_list_files(). If this variable contains a valid value,
OpenDoors will pause the listing of files after every screen, and
give the user the option of continuing, aborting, or disabling
the "Continue?" prompt for the rest of the file listing. Thus, if
you are using the od_list_files() under a system that does not
produce one of the door information files listed above, you may
wish to obtain the user's screen length from the user themselves.
If the screen length is not available from the particular type of
door information file that is found, and you do not set this
OpenDoors Door Toolkit Manual - Version 4.10 Page 142
value yourself, this variable will default to 23. If you are
going to set the value of this variable yourself, you should do
so after having called od_init() or some OpenDoors door driver
function.
--------------------------------------------------------------------------------
user_ unsigned char od_control.user_screenwidth;
screenwidth
This variable contains a value representing the width of the
user's screen, and will most often be equal to 80. This variable
is only available under systems that produce a CHAIN.TXT or RA
1.00 and later style extended EXITINFO.BBS door information file.
--------------------------------------------------------------------------------
user unsigned int od_control.user_security;
_security
This variable contains a numerical value representing the user's
security access level on the BBS. You may wish to use this value
to determine wether or not the current user of your door should
have access to certain sysop-only functions. In this case, you
may wish to have a configuration file used by your door, in which
the sysop may define the minimum security level for sysop access.
You would then be able to compare this configuration setting to
the security level stored in this variable, in order to determine
whether or not sysop function should be available. An alternative
method, used by the EZVote sample door, of determining whether or
not the current user is the sysop is to compare the user's name
with the value of the od_control.sysop_name variable. This method
has the advantage of not requiring a configuration program, but
the disadvantage that the door will not function correctly under
all BBS systems, as the od_control.sysop_name variable is not
available under all BBS systems.
The od_control.user_security variable is available under BBS
systems that produce any of the following door information file
formats: CHAIN.TXT, EXITINFO.BBS, PC-Board/GAP and Wildcat style
DOOR.SYS, SFDOORS.DAT or CALLINFO.BBS.
--------------------------------------------------------------------------------
user_sex char od_control.user_sex;
This variable contains a single character representing the gender
of the user that is currently online. This variable will contain
an upper-case 'F' if the user is female, and an upper-case 'M' if
the user is male. This variable is only available under systems
that produce a CHAIN.TXT file.
--------------------------------------------------------------------------------
OpenDoors Door Toolkit Manual - Version 4.10 Page 143
user_subdate char od_control.user_subdate[9];
This variable is a string, in the same format as the
od_control.user_lastdate variable, which stores the date of
expiry of the user's subscription to the BBS. This variable is
only available under systems which produce a PC-Board/GAP and
Wildcat style DOOR.SYS or RA 1.00 and later style extended
EXITINFO.BBS door information file.
--------------------------------------------------------------------------------
user int od_control.user_timelimit;
_timelimit
This variable contains the amount of time, in minutes, that the
user has left in the door. Note that this value may or may not be
equal to the total amount of time that the user has left on the
BBS, depending upon whether the BBS or a third-party door manager
program only allows a limited amount of time in this door. This
variable contains a valid value after od_init() or some OpenDoors
door driver function has been called. OpenDoors uses this
variable to keep track of how much time the user has left in the
door, and will automatically warn the user when nearly all of his
or her time has been used up. OpenDoors will also force the user
out of the door when their time in the door has expired.
OpenDoors automatically subtracts one minute from this variable
every minute that OpenDoors is active, unless chat mode has been
activated (in which case the user's time will freeze), and also
adjusts the value of this variable when the sysop uses the time
adjustment function keys. Hence, you will not normally have any
need to alter the value of this variable yourself. However, there
may be some cases in which you wish to subtract a penalty or add
a bonus to the user's time, such as in a "timebank" door or a
door game that permits the user to "gamble time".
Depending on which BBS system your door is running under, the
value of this variable may or may not effect the user's time left
upon return to the BBS. The BBS system will either reset the
user's time to the value re-written to the door information file
(this variable), or will always subtract the amount of time spent
in the door from the user's remaining time. Other BBS systems,
such as Apex, give the sysop an option of which means should be
used.
This variable is available under all door information file
formats.
--------------------------------------------------------------------------------
user unsigned int od_control.user_todayk;
_todayk
This variable contains the total kilobytes of files that the
current user has downloaded from the BBS during the current day,
and is available under systems that produce EXITINFO.BBS, PC-
OpenDoors Door Toolkit Manual - Version 4.10 Page 144
Board/GAP and Wildcat style DOOR.SYS, or SFDOORS.DAT format door
information files.
--------------------------------------------------------------------------------
user_upk unsigned int od_control.user_upk;
This variable contains the total kilobytes of files that the
current user has uploaded to the BBS, and is available under
systems that produce EXITINFO.BBS, Wildcat style DOOR.SYS or
SFDOORS.DAT files.
--------------------------------------------------------------------------------
user_uploads unsigned int od_control.user_uploads;
This variable contains the total number of files that the current
user has uploaded to the BBS, and is available under systems that
produce EXITINFO.BBS, PC-Board/GAP and Wildcat style DOOR.SYS, or
SFDOORS.DAT format door information files.
--------------------------------------------------------------------------------
user char od_control.user_wantchat;
_wantchat
This variable is a boolean value which indicates whether or not
the user wishes to chat with the sysop (ie, the user has paged
the sysop, but has yet to receive a chat with the sysop). This
variable is used under all door information file formats.
However, changes to this variable are only reflected on the BBS
when the door is running under a system that produces an
EXITINFO.BBS door information file.
This variable is automatically turned on (ie., set to TRUE), when
the user begins to page the sysop for chat, within the od_page()
function, and is automatically turned off (ie., set to FALSE),
when the sysop breaks in for chat via the chat function key.
Also, setting this variable to TRUE will turn on the flashing
want-chat indicator on the OpenDoors status line.
--------------------------------------------------------------------------------
user unsigned int od_control.user_xi_record;
_xi_record
This variable contains the number of the user's record in the
USERXI.BBS file, if any. This variable is only available under
system that produce a Remote Access 1.00 and later style extended
door information file.
OpenDoors Door Toolkit Manual - Version 4.10 Page 145
CONTROL STRUCTURE - DOOR SETTINGS
--------------------------------------------------------------------------------
This section deals with those variables in the OpenDoors control
structure which reflect the current door settings. These
variables are as follows:
od_okaytopage Controls whether the user is currently
permitted to page the sysop.
od_pageendmin End of valid paging hours.
od_pagestartmin Start of valid paging hours.
od_user_keyboard_on Controls whether OpenDoors will
currently accept input from the remote
user's keyboard.
sysop_next Indicates whether or not the sysop has
reserved use of the system after the
current calls.
--------------------------------------------------------------------------------
od char od_control.od_okaytopage;
_okaytopage
This variable allows you to control whether or not the user is
currently permitted to page the sysop via the od_page() function.
This variable contains one of three values. A value equal to TRUE
indicates that paging is currently permitted. A value equal to
FALSE indicates that paging is not current permitted. A value of
MAYBE indicates that the od_page() function should check the
values of the od_pagestartmin and od_pageendmin variables in
order to determine whether or not paging should be permitted. If
you wish to always permit sysop paging, you can simply leave this
variable set at its default value of TRUE. On the other hand, you
may wish to allow the sysop to configure paging hours - either
within your own configuration program, or within the BBS's
configuration. In this case, you can either turn paging on and
off manually by changing the value of this variable, or by
setting this variable to MAYBE, and using the od_pagestartmin and
od_pageendmin variables. These two variables are described below.
For more information on the od_page() function itself, see page
92.
--------------------------------------------------------------------------------
od unsigned int od_control.od_pageendmin;
_pageendmin
OpenDoors Door Toolkit Manual - Version 4.10 Page 146
This variable can be used to set the beginning of valid sysop
paging hours within the od_page() function. If the
od_control.od_okaytopage variable (which is described above) is
set to MAYBE, then OpenDoors will check the value of this
variable prior to paging the sysop via the od_page() function.
This variable should contain the time at which the valid sysop
paging hours end, represented as the a number of minutes since
midnight. For more information on the od_page() function itself,
see page 92.
--------------------------------------------------------------------------------
od unsigned int od_control.od_pagestartmin;
_pagestartmin
This variable can be used to set the beginning of valid sysop
paging hours within the od_page() function. If the
od_control.od_okaytopage variable (which is described above) is
set to MAYBE, then OpenDoors will check the value of this
variable prior to paging the sysop via the od_page() function.
This variable should contain the time at which the valid sysop
paging hours begin, represented as the a number of minutes since
midnight. For more information on the od_page() function itself,
see page 92.
--------------------------------------------------------------------------------
od_user char od_control.od_user_keyboard_on;
_keyboard_on
This variable is a boolean value, indicating whether OpenDoors
will currently accept input from a remote user. OpenDoors
provides a function key (usually [ALT]-[K], unless you have
changed the default), which will allow the sysop to temporarily
prevent the user from having any control over the door. When the
sysop activates this feature, a flashing [Keyboard-Off] indicator
will appear on the status line, and this variable will be set to
FALSE. When the sysop presses the [ALT]-[K] combination a second
time, to toggle the user's keyboard back on, the flashing
indicator will disappear, and this variable will be set back to
TRUE.
--------------------------------------------------------------------------------
sysop_next char od_control.sysop_next;
This variable is a boolean value, indicating whether or not the
"sysop next" feature has been activated. The "sysop next"
feature, which reserves the system for the sysop after the call
has ended, can be toggled on and off within OpenDoors by use of a
function key (Alt-N by default). Also, when the "sysop next"
feature has been activated, an indicator will appear on the
OpenDoors status line. This variable is only available under
systems that produce an SFDOORS.DAT or RA 1.00 and later style
extended EXITINFO.BBS door information file. For more information
OpenDoors Door Toolkit Manual - Version 4.10 Page 147
on testing the type of door information file available, please
see page 125.
OpenDoors Door Toolkit Manual - Version 4.10 Page 148
CONTROL STRUCTURE - OPENDOORS CUSTOMIZATION
--------------------------------------------------------------------------------
The OpenDoors control structure provides many variables which
allow you to customize OpenDoor's behaviour and appearance. These
customization variables fit into one of the following categories:
General Behaviour Customization Variables
Sysop Function Keys Customization Variables
Colour Customization Variables
Language-Specific Prompts Customization Variables
This section deals with those variables that fit into the first
category, "General Behaviour Customization Variables". The other
categories are dealt with in the following sections of this
chapter.
Below is a brief overview of the variables grouped into this
section of the OpenDoors control structure. Following the
overview is a detailed description of each of these variables.
od_box_chars Array of characters used by the
od_draw_box() function
od_before_exit Function to call prior to exiting
od_cafter_chat Function to call after sysop chat
od_cafter_shell Function to call after DOS shell
od_cbefore_chat Function to call prior to sysop chat
od_cbefore_shell Function to call prior to DOS shell
od_clear_on_exit Controls whether the screen is cleared
upon door exit
od_colour_delimiter Indicates what character should delimit
imbedded colour codes for the
od_printf() function.
od_disable Disable OpenDoors activities such as
reading door information file and
monitoring carrier detect / remaining
time
od_inactivity Controls user inactivity timeout
od_last_input Indicates whether the last input came
from the remote user (==0) or the local
sysop (==1).
OpenDoors Door Toolkit Manual - Version 4.10 Page 149
od_list_pause Controls whether or not the user may
pause display within the od_list_files()
and od_send_file() functions by using
the [P] key.
od_list_stop Controls whether or not the user may
terminate display within the
od_list_files() and od_send_file()
functions using [S], [CTRL]-[K], etc.
od_logfile_disable Prevents the logfile from being opened
when od_log_open() is called.
od_logfile_name Contains the filename and possibly path
of the logfile.
od_maxtime Indicates the maximum length of time any
user is permitted to use the door.
od_maxtime_deduction Indicates the amount of time that has
temporarily been taken away from the
user's remaining time, as a result of
the maximum door time settting.
od_nocopyright Prevents OpenDoors from displaying it's
name and version number when a door
program begins execution.
od_noexit Prevents OpenDoors from exiting when the
od_exit() function is called
od_page_len Controls length of the sysop page beep.
od_page_pausing Enables or disables page pausing in
od_send_file(), od_hotkey_menu() and
od_list_files() functions.
od_page_startmin Indicates the time of day at which sysop
paging is first enabled.
od_page_endmin Indicates the time of day at which sysop
paging is disabled.
od_spawn_freeze_time Indicates whether the user's time
remaining continues to be decreased
during the execution of the
od_spawn...() functions (FALSE), or if
the timer should be "frozen" (TRUE).
od_swapping_disable Disables swapping during DOS shell and
od_spawn...() functions
od_swapping_noems Prevents swapping form being done to EMS
expanded memory.
OpenDoors Door Toolkit Manual - Version 4.10 Page 150
od_swapping_path Location where disk swap file should be
created.
od_status_on Controls whether the status line sub-
system is active
--------------------------------------------------------------------------------
od_box char od_control.od_box_chars[6];
_chars
This variable allows you to specify which character the
od_draw_box() function uses in drawing the boarder of a window.
The elements of this array are as follows:
od_control.od_box_chars[0] - Upper left corner of box
od_control.od_box_chars[1] - Horizontal line
od_control.od_box_chars[2] - Upper right corner of box
od_control.od_box_chars[3] - Vertical line
od_control.od_box_chars[4] - Lower left corner of box
od_control.od_box_chars[5] - Lower right corner of box
--------------------------------------------------------------------------------
od_before void (*od_control.od_before_exit)();
_exit
This variable contains a pointer to a function which OpenDoors
should call prior to exiting, or NULL if you do not wish to have
any function called at exit time. For an example of the use of
this variable, see the description of the EZVote demo door, which
begins on page 25.
--------------------------------------------------------------------------------
od_cafter void (*od_control.od_cafter_chat)();
_chat
The function pointed to by this variable will be called after
sysop chat mode has ended. This may be useful for allowing you to
save the user's screen contents prior to chat, and restoring the
afterwards. If this variable contains its default value of NULL,
no function will be called. To alter the string of text which is
displayed after sysop chat, see the od_control.od_after_chat
variable, which is described in the section on the prompts
customization portion of the control structure.
--------------------------------------------------------------------------------
od_cafter void (*od_control.od_cafter_shell)();
_shell
The function pointed to by this variable will be called after the
sysop has returned from a DOS shell. If this variable contains
its default value of NULL, no function will be called. To alter
OpenDoors Door Toolkit Manual - Version 4.10 Page 151
the string of text which is displayed after a DOS shell, see the
od_control.od_after_shell variable, which is described in the
section on the prompts customization portion of the control
structure.
--------------------------------------------------------------------------------
od_cbefore void (*od_control.od_cbefore_chat)();
_chat
The function pointed to by this variable will be called prior to
entering sysop chat mode. This may be useful for allowing you to
save the user's screen contents prior to chat, and restoring the
afterwards. If this variable contains its default value of NULL,
no function will be called. To alter the string of text which is
displayed prior to sysop chat, see the od_control.od_before_chat
variable, which is described in the section on the prompts
customization portion of the control structure.
--------------------------------------------------------------------------------
od_cbefore void (*od_control.od_cbefore_shell)();
_shell
The function pointed to by this variable will be called prior to
executing a sysop DOS shell. If this variable contains its
default value of NULL, no function will be called. To alter the
string of text which is displayed before a DOS shell, see the
od_control.od_before_shell variable, which is described in the
section on the prompts customization portion of the control
structure.
--------------------------------------------------------------------------------
od_clear char od_control.od_clear_on_exit;
_on_exit
This variable contains a boolean value, which indicates whether
or not you wish OpenDoors to clear the screen prior to exiting.
This variable defaults to a value of TRUE, which causes the
screen to be cleared when a door program exits. However, you may
wish to set this variable to a value of FALSE, which will cause
the contents of the screen to remain unchanged when the door
exits. While setting this variable to FALSE will probably result
in a messy display if the door is to return control to a batch
file, if the door returns directly to the BBS, it will result in
a smoother transition from the door back to the BBS (as the sysop
is not left with a blank screen). If your door has a
configuration file or configuration program, you may wish to have
an option which will allow the individual sysop to determine
whether or not the screen should be cleared when the door exits.
--------------------------------------------------------------------------------
od_colour char od_control.od_colour_delimiter;
OpenDoors Door Toolkit Manual - Version 4.10 Page 152
_delimiter
This variable sets the character that is used to delimit colour
codes in the od_printf() function, and defaults to the back-quote
(`) character. If you wish to be able to display the back-quote
(`) character using the od_printf() function, and thus wish to
use a different character to delimit colour codes in the
od_printf() function, simply set this variable to the alternative
character you wish to use. If you wish to disable the imbedded
colour codes feature of the od_printf() function, simply set this
variable to a value of zero. For more information on od_printf()
imbedded colour codes, see the description of the od_printf()
function, which begins on page 93.
--------------------------------------------------------------------------------
od_disable char od_control.od_disable;
This variable is a bit-mapped flag which can be used to disable
certain OpenDoors features which are normally active, in order to
allow for maximum customization of OpenDoors. Each bit of this
variable represents a different feature that can be disabled. To
DISABLE a feature, you set the bit that corresponds to the
particular feature. To ENABLE the feature, the bit is reset. Each
bit is represented by a keyword, as follows:
DIS_INFOFILE - Setting the DIS_INFOFILE bit of the
od_control.od_disable variable allows you to prevent
OpenDoors from reading or re-writing a door information
file. If you wish to disable OpenDoors' reading of the door
information file, you must do so prior to calling od_init()
or any other OpenDoors door-driver functions. At the same
time, you must also manually set any required variables that
are normally set by the information obtained from the door
information file, such as the comm port number, baud rate,
user name, and so on. You may wish to disable reading of the
door information file in a number of cases. For example, you
may wish to manually read another format of door information
file not supported by OpenDoors, or to obtain the necessary
door information from your program's command line. Also, if
you are using OpenDoors to write a non-door communications
program, such as a terminal program, you want to prevent
OpenDoors from attempting to read a door information file on
startup.
DIS_CARRIERDETECT - Setting this bit allows you to prevent
OpenDoors from exiting when it the carrier detect signal
from the modem disappears. This bit may be set or rest at
any time. If you use this bit to disable OpenDoors' carrier
detection, you will probably want to monitor the state of
the carrier detect signal yourself, using the od_carrier()
function, which is described on page 34.
DIS_TIMEOUT - This flag allows you to prevent OpenDoors from
exiting when the user runs out of time. As with the
DIS_CARRIERDETECT flag, you may set or reset this bit at any
OpenDoors Door Toolkit Manual - Version 4.10 Page 153
time. You will most often want to use this setting when
writing a non-door program, which you would not want to have
exit after a particular amount of time has elapsed. Be sure
that you do not confuse this flag with the user's inactivity
timeout. To disable the inactivity timeout, set the
do_control.od_inactivity variable to 0.
DIS_LOCAL_OVERRIDE - This variable affects OpenDoors' behaviour
when a locked BPS rate is specified in the configuration
file, and another BPS rate is specified in the door
information file. By default, OpenDoors will initialize the
modem at the BPS rate specified in the congiruation file,
unless the BPS rate specified in the door information file
is 0. In this case, the 0 BPS rate is used to indicate that
the door is operating in local mode, and will override the
BPS rate specified in the configuration file. Setting this
flag disables the local mode override, causing the modem to
always be initialized at the locked BPS rate, even when the
door information file specifies that local mode should be
used.
Note that in order to disable the OpenDoors status line, the
od_control.od_status_on variable is used, instead of the
od_disable variable. You may also disable the user's inactivity
timeout by setting the od_control.od_inactivity variable to 0.
The od_control.od_status_on variable is described later in this
section. Also note that you do not need to set this variable in
any program that only uses the BBS interface module of OpenDoors,
as the od_init() function is only called in programs which use
the door driver module.
--------------------------------------------------------------------------------
od unsigned int od_control.od_inactivity;
_inactivity
The OpenDoors door driver has a built in user-inactivity timeout
facility, which will automatically disconnect a user who appears
.to be sleeping at the keyboard. If the user has not pressed any
keys on their keyboard for to great a length of time, they will
be warned that they are about to be disconnected due to
inactivity. If they still do not respond after another few
seconds, OpenDoors will automatically disconnect the user and
return control to the BBS software. The od_control.od_inactivity
variable allows you to set the maximum length of time, in
seconds, after which the user will be disconnected for
inactivity. This variable defaults to a value of 200 seconds. You
may disable OpenDoors' inactivity timeout altogether, by setting
the od_control.od_inactivity variable to a value of 0.
--------------------------------------------------------------------------------
od_last char od_control.od_last_input;
_input
OpenDoors Door Toolkit Manual - Version 4.10 Page 154
Indicates whether the last key retrieved using the od_get_key()
function originated from the remote user, or the local sysop. If
the input originated from the remote, this variable is set to 0.
If the input originated from the local keyboard, this variables
is set to 1.
--------------------------------------------------------------------------------
od_list char od_control.od_list_pause;
_pause
This variable contains a boolean value, which allows you to
control whether or not the user may pause displaying within the
od_list_files() and od_send_file() function. When this variable
is set to its default value of TRUE, the user will be able to
pause the display by pressing the [P] key, and resume display by
pressing any other key. However, the pause feature may be
disabled by setting this variable to FALSE.
--------------------------------------------------------------------------------
od_list char od_control.od_list_stop;
_stop
This variable contains a boolean value, which allows you to
control whether or not the user may abort displaying within the
od_list_files() and od_send_file() function. When this variable
is set to its default value of TRUE, the user will be able to
pause the display by pressing the [S], [CTRL]-[K] or [CTRL]-[C]
keys. However, the stop feature may be disabled by setting this
variable to FALSE.
--------------------------------------------------------------------------------
od_logfile char od_control.od_logfile_disable;
_disable
This variable defaults to the value of FALSE, unless the
"LogfileDisable" option is specified in the configuration file,
in which case the variable will be set to TRUE. If this variable
is set to TRUE, OpenDoors will not write to a logfile, even if
the od_log_open() function is called.
--------------------------------------------------------------------------------
od_logfile char od_control.od_logfile_name[80];
_name
This variable specifies the filename, and optionally the full
path of the logfile where OpenDoors should perform logging. This
variable only has an effect when set prior to calling
od_log_open() or od_log_write(). If the log file name is
specified in the configuration file, that name will be stored in
this variable. If you do not set this variable, and the log file
name is not specified in the configuration file, the default name
OpenDoors Door Toolkit Manual - Version 4.10 Page 155
"DOOR.LOG" will be used. If you wish to set this variable, you
should do so prior to calling the od_init_with_config() function.
--------------------------------------------------------------------------------
od_ unsigned int od_control.od_maxtime;
maxtime
This variable specifies the maximum length of time that any user
is permitted to use the door, and is normally set from a
configuration file option. If upon entering the door, the user's
time remaining online is greater than the od_maxtime setting,
their time remaining is temporarily decreased to the maximum
value. Then upon exit of the door, the number of subtracted
minutes is added back onto the user's remaining time. If the
user's remaining time is less than this value, then the setting
has no effect. A value of 0 disables the maximum time setting
altogether.
--------------------------------------------------------------------------------
od_maxtime int od_control.od_maxtime_deduction;
_deduction
This variable store the amount of time that should be added to
the user's time upon exit of the door, as a result of the maximum
time deduction, described above. If the maximum time feature is
not used, this variable will be given a value of 0.
--------------------------------------------------------------------------------
od_ char od_control.od_nocopyright;
nocopyright
This variable is a boolean value that allows you to prevent
OpenDoors from displaying its name, version number and the
copyright notice when an OpenDoors door program begins execution.
When this variable is set to TRUE, and OpenDoors is running in
registered mode, the OpenDoors name display will be disabled. If
you decide that you must use this variable to remove the version
and name display, I would appreciate it if you were to place a
notice elsewhere indicating that your door is written with
OpenDoors.
--------------------------------------------------------------------------------
od_noexit char od_control.od_noexit;
This variable contains a boolean value, which allows you to
prevent OpenDoors from exiting when shutting down. This may be
useful when you want to have your program to do more processing
after you have called the od_exit() function, or if you do not
wish to have your program exit automatically when the user drops
carrier. Normally, this variable will default to a value of
FALSE, indicating that OpenDoors will exit normally when the
OpenDoors Door Toolkit Manual - Version 4.10 Page 156
od_exit() function is called. However, you may optionally set
this variable to TRUE after od_init() or some OpenDoors door
driver function has been called. In this case, when the od_exit()
function is called, either by your program manually, or
automatically by OpenDoors in response to the user dropping
carrier, etc., OpenDoors will not exit. However, the normal
operations of closing the FOSSIL driver and re-writing the door
information file will be carried out. If you set the od_noexit
variable to TRUE, it will be up to your program to detect the
closing of the door driver by the od_exit() function. The best
way of doing this is to provide a function which is to be called
at the beginning of the od_exit() function, by setting the
od_control.od_before_exit pointer, described above.
--------------------------------------------------------------------------------
od_page char od_control.od_page_len;
_len
This variable allows you to control the length, in seconds, of
the sysop page beep produced when the user pages the sysop via
the od_page() function.
--------------------------------------------------------------------------------
od_page char od_control.od_page_pausing;
_pausing
This variable contains a Boolean value that indicates whether or
not page pausing is enabled in the od_send_file(),
od_hotkey_menu() and od_list_files() functions. The default value
of TRUE indicates that page pausing is enabled. A value of FALSE
indicates that page pausing is disabled.
--------------------------------------------------------------------------------
od_page int od_control.od_pagestartmin;
startmin int od_control.od_pageendmin;
od_page These variables indicate the start and end times for sysop
endmin paging, expressed as the number of minutes past midnight.
Sysop paging will be available through the od_page() function
from the start time, up to but not including the end time.
--------------------------------------------------------------------------------
od_spawn char od_control.od_spawn_freeze_time;
_freeze_time
This variable is a boolean value which indicates whether or not
the user's time remaining is frozen during the execution of one
of the od_spawn...() functions. If this variable is set to TRUE,
the user's time remaining will not decrease during the time that
the od_spawn...() function is executing. However, if this
OpenDoors Door Toolkit Manual - Version 4.10 Page 157
variable is set to FALSE, the user's time remaining will continue
to be subtracted during the execution of the od_spawn...()
function. The default value of this variable is FALSE.
--------------------------------------------------------------------------------
od_swapping char od_control.od_swapping_disable;
_disable
This variable is a boolean value which specifies whether or not
OpenDoors will attempt to swap itself and your entire door upon
DOS shell or a call to one of the od_spawn...() functions. This
variable defaults to FALSE. If set to TRUE, OpenDoors will not
attempt to perform swapping activities.
--------------------------------------------------------------------------------
od_swapping char od_control.od_swapping_noems;
_noems
This variable is a boolean value which can be used to prevent
OpenDoors from swapping to EMS memory. This variable defaults to
the value FALSE. If set to TRUE, OpenDoors will not attempt to
use EMS memory for swapping, and will only swap to disk.
--------------------------------------------------------------------------------
od_swapping char od_control.od_swapping_path;
_path
This variable specifies the drive and directory where OpenDoors
should create its disk swapping file, if applicable. More than
one path can be specified, by seperating the paths with a semi-
colon (;) character.
--------------------------------------------------------------------------------
od_status char od_control.od_status_on;
_on
This variable is a boolean value which allows your program to
completely disable the OpenDoors status line. The variable
defaults to a value of TRUE, which causes the OpenDoors status
line to be controllable by function keys, displayed and updated
as it would normally be. However, if this variable is set to
FALSE, then OpenDoors will not update the status line, nor will
it allow the status line to be re-displayed as a result of one of
the status line ([F1] through [F10]) keys being pressed. When you
change the value of this variable from FALSE to TRUE, OpenDoors
will automatically redisplay the status line. Note, however, that
the status line isn't automatically removed when the value of
this variable is changed from TRUE to FALSE. In order to erase
the status line after resetting the value of this variable, you
should reset the output window to the full screen, by calling the
function window(1,1,25,80). Then manually erase the old status
OpenDoors Door Toolkit Manual - Version 4.10 Page 158
line either by clearing the bottom two lines of the screen, or by
clearing the entire screen.
It is important that you do not confuse the use of this variable
with the od_set_statusline() function, which is described on page
113. When the status line is enabled, the sysop can change which
status line, if any, is being displayed, using the function keys
[F1] through [F10]. The od_set_statusline() function allows your
program to make the same changes to the status line setting which
the sysop can make by pressing one of the function keys. The
status line can be removed from the screen, allowing a full 25
lines of text to be displayed, by pressing the [F10] key, or by
making the appropriate call to the od_set_statusline() function.
Note, however, than when this is done, the status line is still
enabled, and can be turned on by pressing any of the other
function keys. On the other hand, if the status line is turned
off using this variable (od_control.od_status_on), the status
line sub-system will be disabled, and pressing function keys will
not "bring it back". So, if you were writing a program where a
status line would be undesirable - such as a non-door
communications program, you would use the od_control.od_status_on
variable. On the other hand, if you only wanted to temporarily
remove the status line - say in order that all 25 lines of a door
program's output could be viewed - while still allowing the
status line to be turned on with the sysop function keys, you
would use the od_set_statusline() function. For more information
on the od_set_statusline() function, see page 113.
OpenDoors Door Toolkit Manual - Version 4.10 Page 159
CONTROL STRUCTURE - FUNCTION KEYS
--------------------------------------------------------------------------------
Within OpenDoors, as with most BBS software and doors, the sysop
has access to a number of function keys, which permits the sysop
to carry out various functions such as entering chat mode,
hanging up on the user, shelling to DOS, and so on. (For more
information on these function key, see page 26.) The variables in
this section allow you to customize which keys carry out the
standard sysop functions, allowing you to customize your door's
interface to mimic any BBS package. By default, OpenDoors
emulates the function keys used by the Remote Access BBS package,
but you may choose, for example, to have your door use the key
combinations used by PC-Board. In addition, OpenDoors provides an
interface which allows you to add your own function keys which
will be accepted by the door. This could allow you to add
additional features, such as giving the sysop access to a status
screen which displays information about your door.
Many of the variables in this section are unsigned ints, which
represent a sysop key combination such as [ALT]-[H], [F8], or
[CTRL]-[P]. These values are in the same format as is returned by
the Turbo C(++) / Borland C++ bioskey() function. The high-order
byte represents the scan code of the key, and the low-order byte
represents the ASCII value, if any, of the key combination. Note
that a complete tutorial on these key codes is beyond the scope
of this manual. For more information on these key codes, you
should see the documentation on the bioskey() function, which
accompanies your compiler. If you wish to determine the key code
which corresponds to a particular keystroke, there is a simple
program, listed below, which you can compile and use. This
program will simply display the key code for any key pressed,
until you press the [ESCape] key. So, in order to determine the
code for [SHIFT]-[F8], you would simply run this program, press
the [SHIFT]-[F8] key combination on your keyboard, and record the
value displayed on your screen.
#include <bios.h>
int main(int argc, char *agv[])
{
register unsigned int keystroke=0;
while((keystroke&0xff)!=27)
{
keystroke=bioskey(0);
if(keystroke!=0)
{
printf("You pressed %u\n",keystroke);
}
}
OpenDoors Door Toolkit Manual - Version 4.10 Page 160
}
--------------------------------------------------------------------------------
BUILT IN These variable allow you to customize the sysop function keys
FUNCTION which control functions such as hanging up on the user, shelling
KEYS to DOS, and so on. All of these variable will be assigned default
values, which correspond to the same function keys used by the
RemoteAccess BBS package. However, you may change the values of
these variables in order to customize the key combinations which
carry out these functions in your own door program. Remember that
if you wish to change the value of any of these variables, you
must do so after having called od_init() or some OpenDoors door
driver function. Each of these variables contain a scan-code /
ASCII-code combination representing a keystroke, as is described
above. These variables are as follows:
+---------------------+-----------------------------------------+
| VARIABLE | CORRESPONDING FUNCTION |
+---------------------+-----------------------------------------+
| od_control. | Enter sysop chat mode |
| key_chat | (Normally [ALT]-[C] |
| | |
| od_control. | Invoke sysop DOS shell |
| key_dosshell | (Normally [ALT]-[J] |
| | |
| od_control. | Return to the BBS without hanging up |
| key_drop2bbs | (Normally [ALT]-[D]) |
| | |
| od_control. | Hangup on the user |
| key_hangup | (Normally [ALT]-[H]) |
| | |
| od_control. | Turn off the user's keyboard |
| key_keyboardoff | (Normally [ALT]-[K]) |
| | |
| od_control. | Decreases the user's remaining time |
| key_lesstime | (Normally [DOWN-ARROW]) |
| | |
| od_control. | Lock the user out of the BBS system |
| key_lockout | (Normally [ALT]-[L]) |
| | |
| od_control. | Increases the user's remaining time |
| key_moretime | (Normally [UP-ARROW]) |
| | |
| od_control. | Array of eight function keys to set the |
| key_status[8] | current status line. |
| | (Normally [F1], [F2], [F3], [F4], [F5], |
| | [F6], [F9], [F10]) |
| | |
| od_control. | "Sysop next" toggle key |
| key_sysopnext | (Normally [ALT]-[N]) |
+---------------------+-----------------------------------------+
--------------------------------------------------------------------------------
OpenDoors Door Toolkit Manual - Version 4.10 Page 161
CUSTOM In addition to the sysop function keys built into OpenDoors, you
FUNCTION may wish to add your own function keys to your door. For example,
KEYS you might wish to have the [ALT]-[Z] combination display a window
of information about your door, or you may wish to add your own
user editor to your door, accessible through the [ALT]-[E]
combination. The three variables:
unsigned char od_control.od_num_keys;
unsigned int od_control.od_hot_key[16];
unsigned int od_control.od_last_hot;
provide your program with an interface to add your own sysop
function keys (not accessible by the remote user) to the door you
have written.
OpenDoors allows you to define up to sixteen custom sysop
function keys. The key codes (as described at the beginning
of this section) are stored in the od_control.od_hot_key[]
array, and the od_control.od_num_keys variable records the
number of keys which have been defined. The
od_control.od_num_keys variable defaults to a value of 0.
So, in order to add your own function keys, simply place the
key codes for these keys in the first n elements of the
od_control.od_hot_key[] array, and set the
od_control.od_num_keys variable to the number of keys you
have defined. OpenDoors will then watch the keyboard for any
of your predefined sysop function keys being pressed. If one
of these keys is pressed, OpenDoors will place the key code
of the pressed key in the od_control.od_last_hot variable.
Your program will then be able to respond to one of your
custom function keys being pressed by checking the value of
the od_control.od_last_hot variable. At any time this
variable contains a non-zero value. If this is the case, you
will then be able to determine which of your function keys
has been pressed by checking the key code contained in this
variable. After taking the appropriate action for the key
pressed, you should be sure to reset the value of the
od_control.od_last_hot variable back to zero, which will
indicate to OpenDoors that your program has received and
responded to the function key which was pressed.
OpenDoors Door Toolkit Manual - Version 4.10 Page 162
CONTROL STRUCTURE - COLOUR CUSTOMIZATION
--------------------------------------------------------------------------------
The OpenDoors control structure variables listed in this section
allow you to customize the colour of text displayed by several of
the OpenDoors functions. Each of the variables in this section
are unsigned chars, which contain the IBM-PC colour attribute of
the colour to be displayed. For more information on these colour
attributes, see the description of the od_set_attrib() function
on page 105. These colour variables are listed below, along with
a description of where each colour is used:
+---------------------+-----------------------------------------+
| VARIABLE | WHERE COLOUR IS USED |
+---------------------+-----------------------------------------+
| od_control. | Text typed by the sysop in chat mode |
| od_chat_colour1 | |
| | |
| od_control. | Text typed by the user in chat mode |
| od_chat_colour2 | |
| | |
| od_control. | File description fields in FILES.BBS |
| od_list_comment_col | listings |
| | |
| od_control. | Filename fields in FILES.BBS listings |
| od_list_name_col | |
| | |
| od_control. | "Missing" string in FILES.BBS listings |
| od_list_offline_col | |
| | |
| od_control. | File size fields in FILES.BBS listings |
| od_list_size_col | |
| | |
| od_control. | Title fields in FILES.BBS listings |
| od_list_title_col | |
+---------------------+-----------------------------------------+
OpenDoors Door Toolkit Manual - Version 4.10 Page 163
CONTROL STRUCTURE - TEXT CUSTOMIZATION
--------------------------------------------------------------------------------
In addition to the other aspects of OpenDoors which may be
customized by use of the OpenDoors control structure, all of the
text displayed by OpenDoors may also be customized. This may be
done either to create doors with OpenDoors that use languages
other than English, or to simply give your doors a "personal
touch". The variables described in this section allow you to
define what text you want to have displayed by OpenDoors at any
time. All of these variables are pointers to strings, and are set
to default values in the od_init() function. Thus, if you wish to
change the string pointed to by any of these variables, you must
do so after od_init() or some OpenDoors doordriver function has
been called. To set any of these variables, you can simply set
them to point to a string-constant in your program. For example,
to set the text displayed by OpenDoors prior to a DOS shell, you
could:
od_control.od_before_shell=(char *)"\n\rJust a moment...\n\r";
The chart below lists each of the text customization variables
(without the "od_control." prefix, for the sake of brevity),
along with their default strings.
Note that some of these strings MUST always be the same length as
their default string. You may not display longer text within
these strings, and if you wish to display shorter text, you must
pad the remaining space in the string with spaces, in order to
preserve its length. Those string which must be of fixed length
also have their length listed in the chart below. Any strings
which have an asterisk (*) in their length column may be any
length.
Also keep in mind that any string with "printf-style" formatting
sequences, such as "%s", must retain the same sequences in the
same order.
In addition, four of these pointers - od_after_chat,
od_after_shell, od_before_chat and od_before_shell - can be set
to a value of NULL. In this case, OpenDoors will not display any
string where this variable's string is normally displayed.
+-----------------------+-----+----------------------------------------------+
| VARIABLE NAME | LEN | DEFAULT VALUE |
+-----------------------+-----+----------------------------------------------+
| od_after_chat | * | "\n\rChat mode ended...\n\r\n\r" |
| | | |
| od_after_shell | * | "\n\r...Thanks for waiting\n\r\n\r" |
| | | |
| od_before_chat | * | "\n\rSysop breaking in for chat...\n\r\n\r" |
| | | |
OpenDoors Door Toolkit Manual - Version 4.10 Page 164
| od_before_shell | * | "\n\rPlease wait a moment...\n\r" |
| | | |
| od_chat_reason | * | " Why would you " |
| | | "like to chat?\n\r" |
| | | |
| od_continue | * | "Continue? [Y/n/=]" |
| | | |
| od_continue_no | char| 'N' |
| | | |
| od_continue_nonstop | char| '=' |
| | | |
| od_continue_yes | char| 'Y' |
| | | |
| od_day[0] | 3 | "Sun" |
| | | |
| od_day[1] | 3 | "Mon" |
| | | |
| od_day[2] | 3 | "Tue" |
| | | |
| od_day[3] | 3 | "Wed" |
| | | |
| od_day[4] | 3 | "Thu" |
| | | |
| od_day[5] | 3 | "Fri" |
| | | |
| od_day[6] | 3 | "Sat" |
| | | |
| od_help_text | 80 | " Alt: [C]hat [H]angup [L]ockout [J]Dos " |
| | | "[K]eyboard-Off [D]rop to BBS " |
| | | |
| od_help_text2 | 79 | " OpenDoors 4.10 - (C)Copyright 1992, " |
| | | "Brian Pirie - Registered Version " |
| | | |
| od_inactivity_timeout | * | "User sleeping at keyboard, inactivity " |
| | | "timeout...\n\r\n\r" |
| | | |
| od_inactivity_warning | * | "Warning, only %d minute(s) remaining " |
| | | "today...\n\r\n\r" |
| | | |
| od_month[0] | 3 | "Jan" |
| | | |
| od_month[1] | 3 | "Feb" |
| | | |
| od_month[2] | 3 | "Mar" |
| | | |
| od_month[3] | 3 | "Apr" |
| | | |
| od_month[4] | 3 | "May" |
| | | |
| od_month[5] | 3 | "Jun" |
| | | |
| od_month[6] | 3 | "Jul" |
| | | |
| od_month[7] | 3 | "Aug" |
| | | |
| od_month[8] | 3 | "Sep" |
OpenDoors Door Toolkit Manual - Version 4.10 Page 165
| | | |
| od_month[9] | 3 | "Oct" |
| | | |
| od_month[10] | 3 | "Nov" |
| | | |
| od_month[11] | 3 | "Dec" |
| | | |
| od_no_keyboard | 10 | "[Keyboard]" |
| | | |
| od_no_sysop | * | "\n\rI'm afraid the sysop is not available " |
| | | "at this time.\n\r" |
| | | |
| od_no_response | * | " No response.\n\r\n\r" |
| | | |
| od_no_time | * | "Sorry, you have used up your time for " |
| | | "today...\n\r\n\r" |
| | | |
| od_offline | 10 | "[OFFLINE] " |
| | | |
| od_paging | * | "\n\rPaging Sysop for Chat" |
| | | |
| od_press_key | * | "Press [Enter] to continue..." |
| | | |
| od_status_line[0] | 80 | " " |
| | | " [Node: " |
| | | |
| od_status_line[1] | * | "%s of %s at %u BPS" |
| | | |
| od_status_line[2] | 79 | "Security: Time: " |
| | | " [F9]=Help " |
| | | |
| od_status_line[3] | 80 | "Voice#: Last Call : " |
| | | " First Call : " |
| | | |
| od_status_line[4] | 79 | "Data #: Times Called : " |
| | | " Age : Birthdate : " |
| | | |
| od_status_line[5] | 80 | "Uploads : Downloads" |
| | | " : " |
| | | |
| od_status_line[6] | 79 | "Flags:(A):-------- (B):-------- (C):--" |
| | | "------ (D):-------- " |
| | | |
| od_status_line[7] | * | "%uk, %u files" |
| | | |
| od_status_line[8] | 80 | "Last Caller: T" |
| | | "otal System Calls : [Time: ] " |
| | | |
| od_status_line[9] | 79 | "[Printer: OFF] [Local Screen: ON] " |
| | | " Next Event : " |
| | | |
| od_status_line[10] | <=20| "[none, errorlevel 0]" |
| | | |
| od_status_line[11]] | <=20| "[%5.5s, errorlevel %u]" |
| | | |
| od_status_line[12] | 80 | "Msgs posted : Highread : " |
OpenDoors Door Toolkit Manual - Version 4.10 Page 166
| | | " " |
| | | |
| od_status_line[13] | 79 | "Netmail Credit : Handle : " |
| | | " " |
| | | |
| od_status_line[14] | * | " Reason for chat : %-60.60s" |
| | | |
| od_sysop_next | 5 | "[SN] " |
| | | |
| od_time_left | 10 | "%d mins " |
| | | |
| od_time_warning | * | "Warning, only %d minute(s) remaining tod" |
| | | "ay...\n\r\n\r" |
| | | |
| od_want_chat | 11 | "[Want-Chat]" |
+-----------------------+-----+----------------------------------------------+
OpenDoors Door Toolkit Manual - Version 4.10 Page 167
--------------------------------------------------------------------------------
CHAPTER 6 - DEBUGGING OPENDOORS PROGRAMS AND GETTING HELP
--------------------------------------------------------------------------------
ABOUT THIS CHAPTER
--------------------------------------------------------------------------------
This chapter is perhaps the most important section of this entire
manual. Here, we provide detailed instructions to help you in
tracing the source of problems in programs written with
OpenDoors. Included in this chapter is a step-by-step OpenDoors
troubleshooting guide and a chart listing common problems and
their solutions. Also included in this chapter is information on
the many means available to you for getting more help with
OpenDoors, including the OpenDoors support BBS, the OpenDoors
EchoMail conference, and how to get in touch with me. It is
strongly encouraged that you take the time to read through this
chapter.
TROUBLESHOOTING PROBLEMS
--------------------------------------------------------------------------------
If you are experiencing difficulty with a program that you are
writing using OpenDoors, it is suggested that you follow the
steps listed below in order to quickly solve your problem. Also,
be sure to check to "solutions to common problems" section of
this manual. There are many common difficulties which people have
with OpenDoors, that can easily be fixed using the instructions
in the "common solutions" section. Also, if you are having
difficulty solving a problem yourself, do not hesitate to get in
touch with me, as I am always happy to help with any problems. In
addition, you may find the other means of OpenDoors support
(described latter in this chapter), invaluable in solving
difficulties with OpenDoors.
Keep in mind that most programs you write will have some "bugs"
to begin with, and you should expect to spend at least 50% of any
programming project tracing down and solving errors and bugs.
While it would be nice if every program written worked correctly
the first time, it is a fact of life that debugging is and always
has been an important part of the software life-cycle. In fact,
what most often separates the good programs from the bad is the
amount of time their programmer's spend debugging and improving
them. Unfortunately, it is difficult, if not impossible, to come
up with a "magic formula" for debugging software. Debugging
software is really more of an art than a science. However, there
are some basic guidelines, which if followed, can greatly ease
the task of software debugging.
OpenDoors Door Toolkit Manual - Version 4.10 Page 168
As with all problem solving, the secret to software debugging
lies in obtaining as much information about the problem as
possible. While it is sometimes possible to solve a bug by making
intuitive changes in your program, or in re-writing a piece of
code to solve the problem by a different means, debugging most
often requires more of a "planned attack". This planned attack
generally involves little more than learning as much about what
is going wrong as possible. The first step in solving a bug
usually lies in locating the source of the problem. Once you have
located the problem, solving it is often a relatively simple
procedure. In locating the source of your bug, the use of a
software debugger, such as the one built into the Turbo C(++) /
Borland C++ integrated development environment, can be
invaluable.
When debugging programs written with OpenDoors, you should also
follow the steps listed below, in order to obtain more
information related to the problem you are trying to solve:
1.) Re-read the section(s) of this manual, your Turbo C(++) /
Borland C++ manuals and your program's source code, which
apply to the problem you are experiencing.
2.) Check the solutions to common problems section below. The
most common problems with OpenDoors can be solved using this
simple chart.
3.) Check the value in the od_errno variable, which will often
provide vital clues as to the source of the problem. Use of
the od_errno variable is described in the section below.
4.) If you are still stuck, please feel more than free to get in
touch with me! (see the end of this chapter for information
on reaching me) I am always more than happy to help with any
OpenDoors or general programming problems!
OpenDoors Door Toolkit Manual - Version 4.10 Page 169
SOLUTIONS TO COMMON PROBLEMS
--------------------------------------------------------------------------------
Below, several common difficulties with OpenDoors are listed,
along with suggested solutions to these problems. If you are
experiencing any difficulty with a program that you have written
with OpenDoors, we would suggest that you read this section
thoroughly. Here, the common problem is listed in the left
margin, and the solutions listed on the right portion of the
page.
--------------------------------------------------------------------------------
PROGRAM 1.) Check that the compiler is able to locate the OpenDoors
WON'T header file, "OPENDOOR.H". This can be accomplished either by
COMPILE placing this header file in the same directory as your other
header files (such as STDIO.H, etc.), or by placing the header
file in the current directory.
2.) Be sure that you are linking your program with the correct
library for the memory model you are using. (See the section on
compiling with OpenDoors). Also be sure that both the source code
file for your program (such as EZVOTE.C) and the library file are
listed in your project file, and that the project file is loaded.
For more information on compilling programs written with
OpenDoors, see page 20.
3.) If you have tried the above solutions, and your program still
won't compile, then the problem is most likely an error in your
source code file. If you are unable to resolve your problem, feel
free to get in touch with me.
--------------------------------------------------------------------------------
SCREEN Sometimes, when compiling an OpenDoors door with some versions of
SCROLLED Borland C++, the local screen will not be scrolled correctly. In
INCORRECTLY this case, although everything works correctly on the remote
screen, the bottom line will not be correctly cleared when the
screen is scrolled. This results in scrolled lines appearing to
be partially repeated on the screen. This problem can be remedied
by including the following line at the beginning of the main()
module of your door program:
directvideo=0;
--------------------------------------------------------------------------------
SCREEN If you are using the od_clr_scr() function to clear the screen,
WILL NOT but are not getting any results, this is likely because the user
CLEAR online has screen clearing turned off. If you wish to force
screen clearing regardless of the user's screen clearing settings
OpenDoors Door Toolkit Manual - Version 4.10 Page 170
(this is probably not a good idea), use the function call
od_emulate(12);
--------------------------------------------------------------------------------
ALT-J KEY If you press the Alt-J function key, but do not get any results,
DOES NOT your problem is likely as a result of lack of memory. If enough
WORK memory is not available to load the command processor (usually
COMMAND.COM) when the Alt-J function key is pressed, OpenDoors
will automatically return to the door.
--------------------------------------------------------------------------------
FIXUP This problem was probably caused by a mismatch between your
OVERFLOW memory model selection in your compiler, and the memory model
ERROR library you are using. See the section on compiling programs with
OpenDoors for more information on the correct library you should
be using for your memory model selection.
--------------------------------------------------------------------------------
DIFFICULTY The OpenDoors built-in terminal emulation routines, od_emulate()
COMPILING and od_send_file() require Turbo C++ or Borland C++ in order to
WITH OLD be compiled into your programs. You may, however, "trick" the old
VERSIONS OF versions of Turbo C into compiling your door, by creating a
TURBO C global variable, _wscroll. Simply place the line:
int _wscroll;
at the beginning of your source code file. You will now be able
to compile your program and use these function under old versions
of Turbo C, however a few of the AVATAR-specific control codes
will not always function correctly.
OpenDoors Door Toolkit Manual - Version 4.10 Page 171
OPENDOORS SUPPORT
--------------------------------------------------------------------------------
The powerful and easy to use door toolkit and BBS interface
package, along with this comprehensive manual are only two parts
of what make up OpenDoors. The third element of OpenDoors is the
extensive OpenDoors support mechanisms. The OpenDoors EchoMail
conference and support BBS each give you a chance to share ideas
and source code with other OpenDoors programmers. You can also
receive help learning OpenDoors or solving difficulties from the
OpenDoors echo and BBS. In addition to these sources, I am also
more than happy to answer any of your questions, or hear any
suggestions for future versions of OpenDoors. The remainder of
this chapter provides more information on the various sources of
OpenDoors support. Also keep your eyes open for the "OpenDoors
Tech Journal", which will soon be available. Included in this
newsletter will be information on OpenDoors and future versions,
questions and answers about OpenDoors and BBS door / utility
programming in general, sample source code, and much more.
THE OPENDOORS SUPPORT BBS
--------------------------------------------------------------------------------
One of the many means of receiving OpenDoors support is via the
OpenDoors BBS. Below is an outline of some of what is available
from the OpenDoors BBS:
- The newest version of this package and the OpenDoors BBS
interface package is always available for download.
- Also available for download is example source code and
other files which you may find helpful when writing
programs with OpenDoors.
- The newest list of OpenDoors distribution sites is
available from the BBS.
- Access to the OpenDoors support conference where
OpenDoors programmers can share ideas, source code, and
receive help with difficulties or with learning
OpenDoors.
- Get in touch with me with any questions, comments,
suggestions or bug reports.
- Other files by yours truly, which may be of use in you
programming, such as a registration key system, and so
on.
OpenDoors Door Toolkit Manual - Version 4.10 Page 172
All users receive full access upon their first call to the
OpenDoors BBS. The North American phone number for the support
BBS is:
+1 613 526 4466
Note that if you are calling from outside of North America, you
may have to add the appropriate long distance routing codes to
the phone number. If you are having difficulty getting through to
the BBS (ie, you get a BUSY signal), it may be best to try again
in ten to twelve hours time. Since the BBS system is sometimes
used for beta test purposes, it may be unavailable for several
hours at a time. The OpenDoors support BBS also has a FidoNet
address, 1:243/8. If you are interested in a list of files
available from the support BBS, simply file-request "FILES". To
receive the newest version of OpenDoors, you can file-request
"ODOORS".
THE OPENDOORS ECHOMAIL CONFERENCE
--------------------------------------------------------------------------------
Also available to OpenDoors users who are a member of FidoNet or
other EMail networks is the OpenDoors EchoMail support conference
(tag-name "OPENDOORS"). The OpenDoors support conference is
devoted to OpenDoors and BBS door and utility programming in
general. As with the OpenDoors support BBS, this conference gives
people programming with OpenDoors a chance to share ideas and
source code. It also is a forum for receiving help either
learning OpenDoors, or with a specific difficulty. Bug reports,
suggestions and information on future versions of OpenDoors is
also available in the OpenDoors conference. For more information
on the OPENDOORS echo, please feel more than free to get in touch
with me.
GETTING IN TOUCH WITH ME
--------------------------------------------------------------------------------
If you have any questions about OpenDoors, would like help with
any programs that your are writing, or have any suggestions for
future versions of OpenDoors, please feel free to get in touch
with me. You can get in touch with me by any of the following
means:
- By calling the OpenDoors support BBS. Information on the
support BBS is provided earlier on in this chapter.
- By electronic mail. My FidoNet NetMail address is:
1:243/8 ***SEE NOTE BELOW***
And my Internet address is:
OpenDoors Door Toolkit Manual - Version 4.10 Page 173
brian@bpecomm.ocunix.on.ca
While I would like to be able to reply to all NetMail messages
by CrashMail, I am afraid I simply can not afford to do this.
So, if you choose to send NetMail, please indicate whether you
would like me to reply by routed NetMail (this may not work,
if routed NetMail is not available in your area), or to place
the message on hold for you to poll and pick up.
- By writing a message to me in the OpenDoors support EchoMail
conference. For more information on the OPENDOORS echo, see
the previous section of this chapter.
- By conventional mail. My postal address is:
Brian Pirie
Apt. 1416 - 2201 Riverside Dr.
Ottawa, Ontario
Canada
K1H 8K9
I try to respond to all correspondences as soon as possible (ie,
within twenty-four hours). However, it is possible that it may
take slightly longer to reply to your message, if you are asking
a question that requires time for me to get an answer, or if I
happen to be away for a few days.
If you are having some sort of difficulty with OpenDoors, the
more detailed information you supply (such as source code to the
program that is causing the problem, how to duplicate the
problem, and so on), the more quickly I will be able to determine
the source of your problem. Also, before you write about a
problem with OpenDoors, you may wish to be sure that you have
read and followed the instructions in the section on
troubleshooting, found on page 168. While I do not mind taking
the time to answer any questions related to OpenDoors, you may be
able to save yourself the time of writing and waiting for a
response - simply by following the instructions in the
troubleshooting section. More often than not, the answer to
questions I receive is already in this manual.
If you have suggestions for enhancements or additions for future
versions of OpenDoors, and are sending your suggestions by
conventional mail, it would be easiest for me if you sent your
suggestions on the suggestion form, located on page 18. If you
have a BBS system, for which you would like to see support added,
and either have the technical information on that BBSes
structures, or know where I could get this information, please
let me know.
OpenDoors Door Toolkit Manual - Version 4.10 Page 174
OPENDOORS DISTRIBUTION SITES
--------------------------------------------------------------------------------
Below is a list of sites from which the newest version of
OpenDoors is available, as of February 25th, 1993, sorted by
country. If you would like to join the list of official OpenDoors
distribution systems, please see the end of this chapter.
Please also keep in mind that I cannot gurantee the accuracy of
the information in the list below. If you are having any
difficulty contacting any of the distribution sites, please let
me know. The only site that I can gurantee OpenDoors to be
available from is the OpenDoors support BBS. For more information
on the OpenDoors support BBS, please see page 172.
In addition to the sites listed below, the newest verion of
OpenDoors will likely be available from any system that carries
"Programmer's Distribution Network" files. Also, if you send a
self-addressed envelope, along with either a 3-1/2" or 5-1/4"
(360K) diskette, and $2.00 to cover postage, I would be happy to
mail the newest version of OpenDoors to you. My address is
included in the list, below.
Also, the newest version of this file is always available for
download or file request from the OpenDoors support BBS, with the
filename OD_SITES.ZIP.
--------------------------------------------------------------------------------
AUSTRALIA Sydney, Australia - Rosalyn Anderson
Data Number : +61 2 552 3255
Modem : 9600, v.32/PEP
Fidonet : 3:712/618
Intlnet : 58:2100/146
Comments : 24 hours - log on as "opendoors user" password
"doors"
Sydney, Australia - Mark Laurence
Data Number : +61 2 938 5707
Modem : 14400, v.32bis/v.42bis
Fidonet : 3:714/910
Comments : 24 hours, file request for nodelisted sysops
--------------------------------------------------------------------------------
CANADA Lancaster Park, Alberta, Canada - Thomas King
Data Number : +1 403 973 6311
Modem : 16800, v.32bis/HST/v.42bis
Fidonet : 1:342/49
IMEX : 89:701/513
Worldnet : 62:3200/50
Comments : Freq by Magic name ODOORS 23hrs/day
Guest Name "Visiting Sysop" PW is "PhoneBill"
Saint John, New Brunswick, Canada - George Hannah
OpenDoors Door Toolkit Manual - Version 4.10 Page 175
Data Number : +1 506 652 7292
Modem : 14400, v.32bis/v.42bis
Fidonet : 1:255/7
Comments : Freq ODOORS, except during ZMH
Login as OPENDOORS password GUEST
Ottawa, Ontario, Canada - Brian Pirie
Data Number : +1 613 526 4466
Modem : 9600, v.32/v.42bis
Fidonet : 1:243/8 *** SEE PAGE 173 ***
Internet : brian@bpecomm.ocunix.on.ca
Postal addr : Brian Pirie
1416 - 2201 Riverside Drive
Ottawa, Ontario
Canada
K1H 8K9
Comments : Freq and BBS available 24 hours / day to
everyone
Mascouche, Quebec, Canada - Robert La Ferte
Data Number : +1 514 968 1709
Modem : 14400, v.32bis/v.42bis
Fidonet : 1:167/235
Comments : BBS opened 24 hours a day, 7 days/week,
file request OPENDOORS for the latest version
--------------------------------------------------------------------------------
ITALY Trieste, Italy - Pietro Budicin
Data Number : +39 40 3783111
Modem : 14400, v.32bis/HST/v.42bis
Fidonet : 2:333/603
Comments : Freq ODOORS and BBS 24hrs/day
--------------------------------------------------------------------------------
UNITED Cambridge, United Kingdom - Marcel Cook
KINGDOM Data Number : +44 223 301487
Modem : 14400, v.32bis
Fidonet : 2:440/34
Comments : 24 hours for callers and file requests
Ipswich, Suffolk, United Kingdon - Mark Clark
Data Number : +44 473 692882
Modem : 14400, v.32bis/v.42bis
Fidonet : 2:440/107
Comments : 24 Hours/Freqs Instant Registration
Mildenhall, Suffolk, United Kingdom - Dale Elrod
Data Number : +44 638 718623
Modem : 16800, v.32bis/HST/v.42bis
Fidonet : 2:440/37
Comments : 23 hours a day,
magic name of OPENDOORS to get latest version
online.
OpenDoors Door Toolkit Manual - Version 4.10 Page 176
--------------------------------------------------------------------------------
UNITED San Jose, California, USA - Darryl Perry
STATES Data Number : +1 408 265 4660
Modem : 9600, v.32/v.42bis
Fidonet : 1:143/324
Comments : Freq the full filename only.
San Ramon, California, USA - Brent Johnson
Data Number : +1 510 830 4616
Modem : 14400, v.32bis/HST
Fidonet : 1:161/610
Comments : 23 hours, FREQ almost anytime if listed in
nodelist.
Columbus, Georgia, USA - Scott Burkett
Data Number : +1 706 596 8126
Modem : 9600, v.32
Fidonet : 1:3613/12
Comments : 24 Hour Operation and FREQ's
Baltimore, Maryland, USA - Mike Gurski
Data Number : +1 410 256 1979
Modem : 14400, v.32bis/v.42bis
Fidonet : 1:261/1062
Echonet : 50:5410/1062
Comments : 24 hour FREQs, unlisted systems welcome
Muskogee, Oklahoma, USA - Vince Jacobs
Data Number : +1 918 687 1612
Modem : 14400, v.32bis/v.42bis
Fidonet : 1:3813/309
DoorNet : 75:7918/200
Comments : 24 Hours, FREQ hours anytime but ZMH,
Guest Log In as The Inspector, password Gadget
OpenDoors Door Toolkit Manual - Version 4.10 Page 177
JOINING THE DISTRIBUTION NETWORK
--------------------------------------------------------------------------------
Essentially, the OpenDoors Distribution Network is a list of
"official" OpenDoors distribution sites that will be distributed
with future versions of OpenDoors, and anyone is welcome to
participate. The idea behind the "OpenDoors distribution network"
is simply to make it easier for you, the OpenDoors programmer, to
obtain OpenDoors updates. While the newest version of OpenDoors
is always available from the OpenDoors Support BBS, and often
from any system carrying the "Programmer's Distribution Network",
most OpenDoors programmers would find it useful to know of a
system closer to them where the newest version of OpenDoors is
always available. Although I would like to be able to send the
newest version of OpenDoors to any support site, the cost of
doing so unfortunately makes this impossible. However, it is
likely that you would pick up the newest version of OpenDoors
when it is available anyhow, so this shouldn't really make any
difference. So, if you are interested in becoming an official
OpenDoors distribution site, simply fill in the form below, and
send it to me, either electronically or by conventional mail at
one of the addresses listed on page 173.
OpenDoors Door Toolkit Manual - Version 4.10 Page 178
OPENDOORS OFFICIAL DISTRIBUTION SITE APPLICATION FORM
-----------------------------------------------------
YOUR NAME : ________________________________________
(eg. Brian Pirie)
LOCATION : ________________________________________
(eg. Ottawa, Ontario, Canada)
DATA NUMBER(S) : ________________________________________
(eg. (613) 526-4466)
NETWORK ADDRESSES: ________________________________________
(eg. 1:243/8 in FidoNet)
MODEM TYPE: ________________________________________
(eg. 9600, V32bis, v42bis, HST)
OTHER INFORMATION: ________________________________________
________________________________________
(eg. Hours of BBS operation, file request hours,
guest login and password, etc.)
I CAN BE INFORMED OF NEW RELEASES BY:
____
| | - ***ROUTED*** FIDONET NETMAIL
|____|
____
| | - OPENDOORS SUPPORT CONFERENCE
|____|
____
| | - OTHER: ________________________________
|____|
OpenDoors Door Toolkit Manual - Version 4.10 Page 179
--------------------------------------------------------------------------------
APPENDIX A - CONTENTS OF ARCHIVE
--------------------------------------------------------------------------------
OpenDoors is usually distributed in the form of a single,
compressed archive file. Thus, you should have received this
version of OpenDoors in a file who's name began with ODOORS41.
The files listed below should be included in your OpenDoors
package. If any of these files are missing, you will probably
want to look for the most recent version of OpenDoors from
another source.
Also, as of OpenDoors 4.00, each file contains the same date and
time. The time listed in a file's directory entry represents the
version number it belongs to, and it's date is the date of that
version's release. Hence, a file with a time of 4:10 is part of
OpenDoors 4.10. This is intended to help in distinguishing
between a file that is part of the current version of OpenDoors,
and one that is part of an older version.
DOOR TESTING DROP FILE
DORINFO1.DEF Sample door info file for testing doors
MISCELLANEOUS EXAMPLE DOORS
EX_HELLO.C Demonstrates how simple a door can be
EX_MUSIC.C Example of ANSI music in OpenDoors
EZVOTE TUTORIAL DOOR
EZVOTE.C Source code to the sample door program
EZVOTE.EXE Sample door program, EZVote
EZVOTE.CFG Sample OpenDoors configuration file
THE LIBRARY FILES
ODOORS.LIB Small memory model library
ODOORC.LIB Compact memory model library
ODOORM.LIB Medium memory model library
ODOORL.LIB Large memory model library
ODOORH.LIB Huge memory model library
THE HEADER FILE
OPENDOOR.H OpenDoors #include .Header file
OPENDOORS DOCUMENATION
ORDER.FRM Easy-to-print order form
OPENDOOR.DOC OpenDoors programmer's manual; this file
OpenDoors Door Toolkit Manual - Version 4.10 Page 180
--------------------------------------------------------------------------------
APPENDIX B - OPENDOORS HISTORY
--------------------------------------------------------------------------------
This section of the manual is a brief history of the additions
and enhancements that OpenDoors has gone through in the process
of getting to where it is today. OpenDoors is constantly being
improved and upgraded, and almost all of the changes are made in
response to requests by current users of OpenDoors. In fact,
almost every reasonable request to date has been implemented in
the current version of OpenDoors. (If you are a registered user
of OpenDoors, do you notice where some of your own suggestions
have been implemented?) If you are upgrading from a previous
version of OpenDoors, this history list will also help you to
identify what new features are available in this version.
VERSION 1.00 Initial beta test version of the OpenDoors doordriver. Proved to
be very bug-free.
VERSION 1.10 Many features have been improved upon and added since version
1.00.
VERSION 1.20 Made several changes:
- Support for the new RemoteAccess 1.00 enhanced
exitinfo.bbs file, with many extra pieces of information.
- Added a Alt-K function key to allow the sysop to
temporarily disable the user's keyboard
- Added full support for turning on and off status line.
Status line has been changed slightly in format, and [F9]
help function key added.
- Improved sysop chat mode (added multi-colour and wordwrap)
- Fixed up shell-to-DOS to automatically shell to the
command processor specified in COMSPEC instead of always
using COMMAND.COM. OpenDoors now also returns to system to
the drive and directory it was in before DOS shell was
issued.
- Added support for the new RemoteAccess "sysop next" key.
VERSION 1.30 A few quick changes to perfect all the features of this version
before beginning major development work on OpenDoors 2.00. Fixed
two problems:
- The status line can no longer be turned back on by the
sysop using F1 - F9 keys when a door program has disable
the status line itself.
OpenDoors Door Toolkit Manual - Version 4.10 Page 181
- A rather major problem was fixed for use of OpenDoors in
conjunction with RA 1.00. We accidentally forgot to save
some of the data that is unused in previous versions, but
is now used in the new version. This bug caused some
unexpected problems, including damage to the USERSXI.BBS
file.
VERSION 1.40 Another maintenance release. This version should now function
perfectly when used in conjunction with older versions of Turbo
C. Other changes in this version include:
- Better error recovery in the case that the door
information file has been damaged.
- OpenDoors was made more customizable, including allowing
the programmer to alter the various OpenDoors messages,
and provisions for user defined function keys for the
sysop. (ie, it is now possible for the programmer to make
Alt-Y another hotkey for the sysop)
VERSION 2.00 Another release, adding a number of new features, such as:
- Added support for AVATAR graphics. OpenDoors will
automatically detect the presence of AVATAR graphics mode
when running under Remote Access, and will allow your door
to toggle it when running under other BBS systems.
- Improved ANSI routines. Added some new functions, and
changed existing functions to send more efficient ANSI
codes in some circumstances.
- The "Sysop Next" key should now work correctly with RA
1.00 and later.
VERSION 2.10 Changes in this version include:
- Implementation of a registration key-code to allow
registered users to more easily upgrade to new versions.
- Added an od_printf() function for ease of formatted output
from within OpenDoors.
VERSION 2.20 More improvements, including:
- Fixing of some minor bugs, such as incorrect handling of
the path to DORINFO1.DEF/EXITINFO.BBS files.
- Added support for more customization, such as hooks for
functions that will be called before and after Shell to
DOS and sysop chat.
- OpenDoors is now DesqView aware. OpenDoors will
automatically detect the presence of DesqView, and uses
the DesqView `virtual screen buffer' for screen display if
present.
OpenDoors Door Toolkit Manual - Version 4.10 Page 182
- A QuickBBS 2.75 compatibility problem has also been fixed.
VERSION 2.30 Fixed a small bug in the registration system.
VERSION 3.00 A major upgrade, released as a beta-test version, including the
following additions/changes:
- Eliminated many bugs.
- Added support for door information files from: WWIV, PC-
Board, Spitfire, WildCat, GAP, TriTel and others.
- Added .ASC/.ANS/.AVT file display support with automatic
interpretation of QBBS/SuperBBS/RA control characters.
- Added ALT-D key to drop the user back to the BBS without
hanging up.
- Added direct access to RA style configuration, file area,
message area, external protocols, event configuration,
caller history, users online, menu files, user base and
other system files.
- Added complete set of message base manipulation routines,
with full support for the RA 1.01 message base locking
scheme.
- The user manual has also been re-written in order to make
it easier to work with.
VERSION 3.10 The following bug fixes and changes have been made since the
release of the beta version, 3.00:
- Time fields in messages are now correctly formatted
- Corrected a bug in the od_set_attrib function where the
intensity setting would not correctly be transmitted to
the remote when using ANSI graphics.
- Fixed a bug in the re-writing of the DORINFO1.DEF which
cause sysop and user's last names to be corrupted.
- Registered users may now disable the display of copyright
and registration information when the door starts up.
VERSION 3.20 A few more changes and bug fixes were made since version 3.10,
including:
- Fixed the FILES.BBS lister to correctly support FILES.BBS
files located in directories other than the default dir,
and added page pausing to the FILES.BBS lister.
VERSION 3.30 The following changes and bug fixes were made since version 3.20:
OpenDoors Door Toolkit Manual - Version 4.10 Page 183
- OpenDoors no longer re-writes the DORINFO1.DEF upon
exiting. No BBS's are known to actually make use of the
information changed in DORINFO1.DEF, and re-writing this
file was causing more troubles than it was worth.
- The od_msg_read_hdr() function's NEXT_MESSAGE command now
works correctly.
- Added an od_errno variable to assist in debugging of
programs written with the BBS file engine portion of
OpenDoors.
VERSION 3.40 A minor upgrade version, with the following changes:
- Fixed a compatibility problem with some locked baud rates.
Now, if OpenDoors receives a baud rate the door
information file that is not supported in the FOSSIL
definitions, it will continue without setting the baud
rate. (Whereas before, OpenDoors would report an error and
exit.)
- Made some changes to the manual, and included a utility to
remove the extended-ASCII characters from the manual to
ease printing on some printers.
VERSION 4.00 This version is a major overhaul of the entire OpenDoors package,
including a great many enhancements and additions. As of version
4.00, OpenDoors is available as two separate packages - the door
programming toolkit (this package), and the BBS interface package
(which is available separately) Among the major changes to
version 4.00 of the OpenDoors door programming toolkit are:
- A complete re-organization of the manual, including the
re-writing of a large portion of the manual. In order to
ease printing on some printers, the manual has been re-
formatted in order that it no longer contains extended
ASCII characters. More thorough documentation on the
OpenDoors functions and structures was written, along with
the addition of many more examples. Also added to the
manual are an index, glossary and other features intended
to make the reference manual an even more powerful and
flexible tool.
- Full support for the changes to RemoteAccess 1.10/1.11 has
been added for version 4.00. These include the addition of
some new fields stored in the EXITINFO.BBS door
information file, and proper adjusting of the user's time
remaining online. Version 4.00 also now has full support
for the new QuickBBS-specific EXITINFO.BBS file.
- All of the text displayed by OpenDoors is now fully
customizable using od_control structure variables. This
permits both greater door customization, and adds the
ability to write 100% non-English doors and programs.
OpenDoors Door Toolkit Manual - Version 4.10 Page 184
- The OpenDoors status lines have been changed. OpenDoors
now provides additional user information through multiple
RemoteAccess-style status lines, accessible through the
F2, F3, etc. keys. Also, the status line may now be turned
off by using the F10 key, allowing the sysop to view all
25-lines of the information displayed by a door program. A
new function od_set_statusline(), permits program
selection of the current status line setting.
- OpenDoors now allows colour codes to be embedded in
od_printf() functions, to eliminate the need for long
chains of alternating od_disp_str(), od_set_colour() /
od_set_attrib() function calls.
- A new formatted input function, od_edit_str() has been
added for use in door programs running in ANSI or AVATAR
graphics mode. The od_edit_str() function features
advanced line editing capabilities which are normally
found only in non-door programs, such as inserting or
deleting text from the middle of a string, moving the
cursor with the arrow keys, and so on. The od_edit_str()
function also provides input formatting, allowing you to
force the user's input into any format you wish, from
phone number formats to date formats to username formats.
The od_edit_str() also provides special modes for
implementing features such as password input, field input
(where the user may move from one field to another using
arrow/tab keys), input field highlighting, editing
existing strings, auto-delete, and much more. The old
od_input_str() function still provides a subset of these
features which do not require ANSI or AVATAR graphics.
- New functions have been added to the door driver module of
OpenDoors. Among these, are an od_putch() function for
displaying one character at a time, and an od_spawn()
function, for easily executing other programs from within
OpenDoors. The od_spawn() function automatically saves the
contents of the current door screen, system drive and
directory, and provides a separate screen on which the
spawned-to program can execute. The od_draw_box() function
allows you to easily display windows in door programs,
using ANSI or AVATAR graphics codes. Also added is are
od_carrier(), od_set_statusline() and od_edit_str()
functions, mentioned elsewhere.
- More changes have been made in order to permit greater
customization and flexibility of OpenDoors. An
od_carrier() function has been added to detect the state
of the carrier detect signal in programs that disable
OpenDoor's internal carrier detection. Also, it is now
possible to shut down OpenDoors without exiting via the
od_exit() function.
- OpenDoors now yeilds the processor to other executing
tasks in multitasking environments (ie. DesqView), when
the door is inactive or waiting for input.
OpenDoors Door Toolkit Manual - Version 4.10 Page 185
- The door driver function od_clr_scr() now only checks the
user's screen clearing setting if that information is
available from the door information file. If the
information is not available, the od_clr_scr() function
will always clear the screen.
- Many other small changes were also made for version 4.00.
Among these, you now have access to the user's reason for
chat and you can switch the pause and stop keys on and off
during listing of available files or displaying a text
file. Also, previous versions of OpenDoors would read the
user's information from the first door information file
found. Instead, version 4.00 now reads the most recently
created door information file. A bug in the od_clr_line()
function has also been fixed.
VERSION 4.10 A great deal of work has been done between version 4.00 and 4.10
of OpenDoors. This work falls into three major categories: bug
fixes, improved performance, and new features. In fact, enough
changes and improvements have been made that this version really
ought to be numbered 5.00. Below is a summary of the changes that
have occurred since version 4.00:
- Much of the door information file interfacing code has
been revamped, in order that OpenDoors now works correctly
with the newest versions of the BBS packages it supports.
OpenDoors now differentiates between three different
DOOR.SYS formats - the DoorWay format, the PC-Board / GAP
format, and the Wildcat format. Also, the SFDOORS.DAT code
has been fixed to correctly work with the newest version
of Spitfire.
- OpenDoors will now attempt to swap itself and your entire
door program to expanded memory or disk when the sysop
shells to DOS, or when you call one of the od_spawn...()
functions. Memory swapping may be configured in a number
of ways, or even disabled. The OpenDoors swapping code
adds only 2K to the door's .EXE file size.
- OpenDoors now includes a new od_spawnvpe() function. In
addition to the features of the "quick-spawn" od_spawn()
function, od_spawnvpe() also returns the errorlevel the
called program returned, allows you to alter the
environment passed to the child process, and uses the same
parameter format as the C spawnvpe() function. (see page
117)
- The od_page() function now checks the sysop paging hours,
set in the OpenDoors control structure. If the user
attempts to page the sysop outside of the defined paging
hours, he or she will be notified that the sysop is not
available.
- OpenDoors now includes a configuration file sub-system
that you may choose to include in your OpenDoors programs.
OpenDoors Door Toolkit Manual - Version 4.10 Page 186
This sub-system automatically parses the configuration
file you specify, responding to any of the built-in
configuration commands, and passing configuration options
specific to your program back to you. With only a single
line of code on your part, this sub-system will allow
people running your program to configure many options such
as sysop paging hours, system directories, maximum time
within the door, etc. It also allows the sysop to provide
information that may not be supplied by their particular
BBS software, such as modem settings, the system's name
and so on. In addition to all these built in commands, you
can add your own configuration options, such as display
colours, registration key numbers and other information
needed by your program - without the need to write your
own configuration file parsing routines. (See page 76)
- OpenDoors now supports custom, sysop-defined door
information file (drop file) formats. By defining a custom
door information file format in the cofiguration file,
OpenDoors door programs can now be made to run directly
under BBS packages that use proprietary file formats that
are not directly supported by OpenDoors. (see page 78)
- In order to make doors written with OpenDoors even more
foolproof for the sysop to setup, an intelligent door
information file (drop file) locator has been added.
OpenDoors will automatically search for a door information
file in the directory specified by the configuration file,
the directory specified by your door's source code, the
current directory, and the directory pointed to by the
environment variables used by any of a number of BBS
packages.
- OpenDoors now includes a log file sub-system that you may
choose to include in your programs. The log file system
handles all access and formatting of the logfile, allowing
the programmer to make log file entries by simple function
calls such as od_write_log("User downloading file");.
Also, since the log file system is closely integrated with
the rest of OpenDoors, choosing to include the logfile
system in a program causes OpenDoors to automatically
output the most common logfile entries for events such as
the user paging sysop, the user hanging up, sysop chatting
with the user, user inactivity timeouts, and so on. (see
page 89)
- OpenDoors 4.00 would not always correctly turn on and off
high intensity or flashing colour attributes in ANSI mode.
The ANSI colour handling code has been reworked for
version 4.10, to eliminate these problems.
- An od_get_answer() function has been added, which can be
used to easily permit only certain keys to be pressed in
response to a prompt. For instance, to get a Yes/No
response from the user, use od_get_answer("YN"); (see page
66)
OpenDoors Door Toolkit Manual - Version 4.10 Page 187
- A popular addition to OpenDoors 4.00 was the ability to
change the current display colour within od_printf()
format strings, using imbedded control characters.
However, the programmer was forced to use a rather cryptic
two-byte control sequence, where the second character of
the sequence contained an 8-bit colour attribute value. It
is now possible to change the display colour within
od_printf() by specifying the names of the desired
foreground and background colours, delimited by a set of
BACK-QUOTE (`) characters. For example:
od_printf("`Red` THIS TEXT IS RED `Blue` THIS TEXT IS BLUE");
od_printf("`Flashing bright green on dark green` AND THIS IS GREEN");
(see page 93)
- Version 4.10 would not correctly "freeze" the user's time
during DOS shell and sysop page operations, when the door
was operating under RemoteAccess 1.11. This has been
fixed.
- A new variable, od_spawn_freeze_time, has been added to
the OpenDoors control structure. When set to FALSE, the
user's time remaining continues to be deducted during the
execution of any of the od_spawn... functions. When set to
TRUE, the user's time remaining is frozen during the
execution of an od_spawn... function.
- The current directory is now correctly restored to its
original setting after the sysop returns from a DOS shell,
and after calls to the od_spawn... functions.
- A number of people were experiencing difficulty using the
od_edit_str() function in version 4.00. A number of
improvements to this function's logic have been made in an
attempt to make od_edit_str() more foolproof to use. Also,
a new flag setting, EDIT_FLAG_LEAVE_BLANK has been added.
However, there were a few reports of problems which we
were not able to reproduce. If you are still having
difficulty with this function, please carefully re-read
the section of the manual pertaining to it's use. In
particular, be sure that your difficulty is not resulting
from the flag settings you are using. If you still suspect
a bug in this function, please include with your bug
report the source code that is causing the problem.
- Page pausing within the od_send_file() and od_list_files()
(FILES.BBS listing routine) functions can now be disabled
and re-enabled by the programmer.
- The "Continue? [Y/n/=]" end of screen prompt and response
keys are now fully customizable.
- The od_list_files() FILES.BBS listing function now works
correctly in all memory models. The function has also been
OpenDoors Door Toolkit Manual - Version 4.10 Page 188
fixed to correctly handle cases where the trailing
backslash is not supplied in the path parameter.
- The actual BBS line (node) number is now displayed on the
default status line, provided that this information is
supplied by the BBS software.
- It is now possible to detect whether keystrokes originated
from the remote or local keyboard. This is a feature that
is useful in some special applications, such as split-
screen sysop chat programs.
- Version 4.00 would not always correctly display the status
lines, if there was information missing from the
EXITINFO.BBS file. This has been fixed. In addition, the
"next event" information is now correctly displayed on the
status lines. Also, if the user's birthday is available,
their age will also be calculated and displayed on the
status line.
- If you temporarily disable inactivity timeouts, OpenDoors
will no longer automatically trigger and inactivity
timeout as soon as you re-enable this feature.
- A new function, od_hotkey_menu(), has been added to
facilitate displaying a menu with "hot keys". Like the
od_send_file() function, od_hotkey_menu() will display an
ASCII, ANSI or AVATAR file. However, od_hotkey_menu() also
allows you to pass a string listing possible hot keys. If
the user presses any of these keys while the menu is being
displayed, menu display will immediately cease, and the
function will return the key pressed by the user. (See
page 71)
- The od_send_file() (the ASCII/ANSI/AVATAR file display
routine) no longer sends the EOF character if it happens
to exist at the end of a file.
- In addition to the EZVote OpenDoors tutorial door, an
number of other example doors are now included in the
OpenDoors package.
- A few errors have been corrected in the documentation, and
additional information has been added about the new
features in this version.
OpenDoors Door Toolkit Manual - Version 4.10 Page 189
--------------------------------------------------------------------------------
APPENDIX C - FUTURE VERSIONS
--------------------------------------------------------------------------------
While I cannot make any promises about what features and changes
will be seen in future versions of OpenDoors, I would like to
take a moment to tell you a bit about some of the features you
can expect to see in future versions of OpenDoors
As you are probably already aware, OpenDoors is a constantly
evolving package. To help meet the needs of programmers working
with OpenDoors, nearly every idea and change that is made to the
package results from the suggestions and comments I receive from
the people using OpenDoors. For this reason, I will most likely
continue to produce new versions of OpenDoors for as long as
there is a demand and ideas for upgrades. There certainly is no
shortage of either of this right now.
Some of the features that are currently in the works for up and
coming version of OpenDoors include:
- The OpenDoors "Multiple Personality System", which will
allow sysops using OpenDoors doors to select from one of
many status line and function key personalities. This will
allow OpenDoors doors to mimic the behaviour of the BBS
package the sysop is most familiar with.
- A built-in automatic ANSI/high-ASCII to plain-ASCII
conversion system.
- More advanced ANSI/AVATAR terminal routines, such as
screen save and restore, window scrolling, and more.
- Direct interfacing with more BBS systems, including
Maximus direct interfacing.
- AVATAR compression.
- Built in ANSI music support, including optional local
sound.
- Improvements to exisiting OpenDoors features, such as more
configuration file options, multiple log file formats, and
many smaller changes.
OpenDoors Door Toolkit Manual - Version 4.10 Page 190
--------------------------------------------------------------------------------
APPENDIX D - SPECIAL THANKS
--------------------------------------------------------------------------------
There are a great many people who I would like to thank, for
their suggestions, ideas and assistance in making OpenDoors what
it is today. In a way, I feel somewhat relucant to list people
names, as I will no doubt forget someone important. Among those I
would like to thank are:
- Everyone who has taken the time to register OpenDoors
- The folks in the OpenDoors EchoMail conference will all of
your suggestions and bug reports.
- Those people in the OpenDoors distribution network, who
help to make OpenDoors available to others.
- In particular I would like to thank the following people
for their devotion of time, in the form of suggestions,
bug reports, sending information, etc.:
Ron Bergeron
Scott Burkett
Mike Hartmann
Winfried Hirsch
Robert La Ferte
Ron Le Blanc
Bill Pavich
OpenDoors Door Toolkit Manual - Version 4.10 Page 191
--------------------------------------------------------------------------------
GLOSSARY
--------------------------------------------------------------------------------
ANSI "ANSI", often referred to as "ANSI Graphics", is a display
protocol which allows (in this case), BBS software to perform
certain display functions such as changing the colour of
displayed text, or moving the location of the cursor on the
screen. The majority, though not all, BBS users use terminal
software with ANSI graphics capabilities. Any users that do not
have graphics display capabilities, will be using ASCII mode,
instead. Compare ASCII and AVATAR.
ASCII ASCII (pronounced "ass-key") is an acronym for "American Standard
Code for Information Interchange", and is a definition of a set
of 128 letters, number and symbols, which can be displayed by
computer systems. Also, when used within the domain of BBS
software, ASCII mode is often used to refer to the lack of any
graphics display capabilities, such as ANSI or AVATAR. When ASCII
mode is used, characters can only be displayed in standard
Teletype fashion, one after another. Also, colour and cursor
positioning functions are not available in ASCII mode. Compare
ANSI and AVATAR.
AVATAR AVATAR is an acronym for "Advanced Video Attribute Terminal
Assembler and Recreator". AVATAR is a graphics display protocol,
similar to ANSI. Like ANSI-graphics, AVATAR graphics allow
functions such as cursor positioning, and colour changing.
However, AVATAR also offers many capabilities not available from
ANSI, and performs the same functions as ANSI much more quickly.
AVATAR graphics is less common than both ANSI or ASCII, but is
becoming more popular as time goes by. Compare ASCII and ANSI.
BAUD For our purposes, the term "baud" or "baud rate" refers to the
speed at which data is being sent from one computer to another
over a modem. Sometimes referred to as "BPS".
BIT-MAPPED As with Boolean values, described below, bit mapped flags
FLAGS are used to indicate whether or not various conditions exist.
(For example, whether or not a certain setting is enabled, or
whether or not a particular event has occurred.) However, unlike
Boolean variables, a single bit-mapped flag represents more than
one of these TRUE/FALSE values. In fact, each bit (BInary Digit),
which makes of the variable can be used to represent a separate
TRUE/FALSE state. (ie, each bit maps to a particular piece of
information, and hence the term "Bit Map").
For an example of using bit-mapped flags, let us take a case of a
single "unsigned char" which contains three independent
TRUE/FALSE values. We will call this variable user_info, and it
will indicate whether or not a user has ANSI graphics, whether or
not the user has screen clearing turned on, and wether or not the
OpenDoors Door Toolkit Manual - Version 4.10 Page 192
user has end-of-page "more" prompts enabled. Internally, the bits
of the user_info variable will be as follows:
Bit: 7 6 5 4 3 2 1 0
| | |
| | +--- ANSI Graphics
| +----- Screen Clearing
+------- More prompts
In this case, we will have three constants which we define in
order to simplify access to these bit-mapped flags, as follows:
#define ANSI_GRAPHICS 0x01
#define SCREEN_CLEARING 0x02
#define MORE_PROMPTS 0x04
Note that normally within OpenDoors, these constants will be
defined for you, and you will have no need to know what their
values are, nor in which bit which piece of information is
stored.
Using bit-mapped flags, you are able to set or clear any of the
individual flags, and check whether any of the flags are set,
using these simple methods: (Not that a set flag is the
equivalent of a Boolean value of "True", and a cleared flag is
the equivalent of a Boolean value of "False".)
Set Flag: variable |= FLAG_CONSTANT;
Clear Flag: variable &=~ FLAG_CONSTANT;
Test Flag: variable & FLAG_CONSTANT
Where "variable" is the name of the bit-mapped flag variable, and
"FLAG_CONSTANT" is the pre-defined constant for the individual
setting. To return to our example, you could turn on the user's
ANSI graphics setting by using the line:
user_info |= ANSI_GRAPHICS;
and to turn off screen clearing you would:
user_info &=~ ANSI_GRAPHICS;
To perform an action (such as waiting for the user to press
[Return]/[Enter]) only if "More" prompts are enabled, you would:
if(user_info & MORE_PROMPTS)
{
... /* Whatever you want */
}
BOOLEAN Many of the variables used within OpenDoors contain a
VALUES "Boolean Value". A Boolean value is a two-state variable, who's
states are referred to as "True" and "False'. If the variable
contains a value of "True", it indicates that a certain condition
OpenDoors Door Toolkit Manual - Version 4.10 Page 193
is so, and if it contains a value of "False", it indicates that
the condition is not so. For example, a Boolean variable "wait"
might be used to indicate whether or not OpenDoors should wait
for the user to press a key, or continue without waiting. In this
case, a value of "True" would indicate that OpenDoors should
wait, and a value of "False" would indicate that it should not
wait.
Note that in the C programming language, there is no actual
Boolean variable type - usually a char or an int are used to
store Boolean values.
The constants TRUE and FALSE, as defined in the OPENDOOR.H file,
are used to represent the two states of a Boolean value. Thus, to
set a boolean variable "wait" to the value of "True", you would
use this line:
wait=TRUE;
and to set the variable "wait" to "False", you would:
wait=FALSE;
However, you SHOULD NOT test whether a Boolean variable is "True"
or "False" by using the C compare (==) operator, as the value
"True" will not always be the same numerical value. (Actually,
the TRUE constant represents just one of many possible numerical
values for "True"). Instead, to perform an action of the "wait"
boolean variable is "True", you would:
if(wait)
{
... /* Whatever you want */
}
and to perform an action if the "wait" boolean variable is
"False', you would:
if(!wait)
{
... /* Whatever you want */
}
For interest sake, Boolean values are named after the 19th
century English mathematician, who studied formal logic, and
created Boolean algebra - an algebra which deals with TRUE and
FALSE values.
BPS BPS is an acronym for "Bits Per Second". For our purposes here,
the terms BPS and BAUD refer to the same thing.
CARRIER The term "Carrier" or "Carrier Detect" refers to a signal which
DETECT most modems send to the computer, which indicates whether or not
the modem is currently connected to (communicating with) another
OpenDoors Door Toolkit Manual - Version 4.10 Page 194
modem. The door driver module of OpenDoors, as with most other
BBS software, uses the status of this carrier detect signal in
order to know whether the user is still connected to the BBS
computer. Thus, if the user hangs up, or if something goes wrong
and the connection is lost, OpenDoors is able to detect this
state, and exit to the BBS. The BBS will then also detect that
the carrier signal has been "lost", and will reset itself, and
then again be ready to accept calls.
CHAT MODE The term "chat mode" refers to a means by which the sysop can
communicate with a user of the BBS / door. During sysop chat,
anything typed by the sysop will appear on the user's screen, and
likewise, anything typed by the user will appear on the sysop's
screen. Sysop chatting is available on both single and multi-line
systems. Sysop chatting is initiated by the sysop, either at any
time a user is online, or specifically in response to a sysop
page.
DOOR A "door" is a program that runs as part of a BBS system, but
which is separate from the central BBS software (RemoteAccess,
Maximus, QuickBBS, PC-Board, etc.) itself. A door provides
additional features not built into the BBS software, such as on-
line games, on-line shopping services, voting booths, match
making systems, access to special files or messages, and much
much more. Since the user also communicates with the door online,
as they do with the BBS, it may not necessarily be obvious to the
user that the door is even a separate entity from the central BBS
software itself.
DOOR DRIVER OpenDoors is broken into two individual, though closely related
package, the door driver module and the BBS interface module. The
door driver module is a complete toolkit used to quickly and
easily write BBS door programs.
DOOR Also referred to as a "drop file", "exit file", or "chain
INFORMATION file". The door information file is a file passed from the
FILE central BBS software to a door program, providing it with
information about the user who is online, the BBS the door is
running under, and the current modem connection. The door
information file may also be used to pass changed information
back to the BBS, such as the amount of time that the user has
used in the door. OpenDoors takes care of all of the work
involved in reading and writing the door information file for
you, as described in the "Basics of Door Programming" section, in
chapter 4. Examples of door information files supported by
OpenDoors include: DOOR.SYS, EXITINFO.BBS, DORINFO?.DAT,
SFDOORS.DAT, CALLINFO.BBS and CHAIN.TXT.
ECHO See "Local Echo".
OpenDoors Door Toolkit Manual - Version 4.10 Page 195
FOSSIL DRIVER The FOSSIL driver, or simply FOSSIL, is a particular computer
program which OpenDoors uses in order to facilitate its
communication with a modem. The FOSSIL driver is either an MS-DOS
device driver or TSR program that is loaded prior to starting up
the BBS or your DOOR, usually from the AUTOEXEC.BAT or CONFIG.SYS
files. The two most commonly used FOSSIL drivers are X00 and BNU.
(FOSSIL is an acronym for "Fido/Opus/SEAdog Standard Interface
Layer", although it has now become the standard for nearly all
BBS software.)
LOCAL MODE The term "local mode" refers to a mode in which a BBS system or
door program may operate. In local mode, the BBS/door behave as
they would if a user were connected via modem to the BBS, except
that all display and input is done simply on the BBS software,
but not through the modem. Local mode allows the sysop or another
person with direct access to the BBS computer to use the BBS/door
software, either for their own user, or for testing that the
software is running correctly. When programming door software,
local mode can be very useful in testing and debugging the door,
without requiring the door to be connected to a remote system.
All doors written with OpenDoors automatically support local mode
operation. Compare "Remote".
LOCAL ECHO The term "Local Echo" refers to a door displaying the same
characters which are sent to the modem on the local screen
("Output Window"). This allows the sysop to view the same
information that is sent to the user's system, in the same manner
that it will appear on the user's screen.
LOCKED (eg. "Locked Baud Rate", "Locked BPS Rate", "Locked Commport
Speed", etc.) Usually, the communication port to which a modem is
connected is set to transfer data at the same BPS rate as the
rate at which the modem is communicating. However, many high
speed modems allow very high speed data transfer by using built-
in data compression methods. In this case, the actual rate of
data transfer can easily exceed the true BPS rate of the
connection. As a result, the BPS rate of the port is kept a
single speed, faster than any of the true modem connections, in
order to increase modem speed performance. This is referred to as
locking the commport BPS rate. OpenDoors has full support for the
use of locked BPS rates.
LOG FILE A log file is a normal text file in which BBS software records
all major activities that have taken place. As such, the log file
permits the sysop, to review what activities have taken place on
the BBS during the time which they have been away from the
computer. A log file can be helpful in identifying system errors
or crashes that have occurred, in alerting the sysop in the case
that any users have been causing problems on the BBS, or in
simply letting the sysop know who has called recently, and what
when they did when they called.
OpenDoors Door Toolkit Manual - Version 4.10 Page 196
MODEM A device connected to a computer which permits it to communicate
with other computers, usually over standard telephone lines.
ONLINE In the case of BBS software and BBS door programs, the term
online refers to the state of a user using the BBS. Usually, the
user will be connected to the BBS from a remote location, using a
modem. However, it is also possible that the user will be using
the actual BBS computer, with the software operating in "local
mode".
OUTPUT WINDOW The local screen of the BBS on which BBS software is running is
usually divided into two sections. At the bottom of the screen,
there is often a one or two line status line, which displays
information to the sysop about the BBS and the user who is
currently online. The rest of the screen is usually an "output
window", in which the information which is being displayed to the
user, is also displayed on the local screen. In some cases, there
will be no status line, in which case the entire screen will be
the output window. Usually, the upper 23 lines of the screen in
an OpenDoors door will be the output window, with the bottom two
lines being the status line. However, it is possible to disable
the OpenDoors status line, in which case the entire screen will
be the output window. See also "Status Line"
PAGE See "SYSOP PAGE"
PARAMETER In the C programming language, many tasks are accomplished by
calling functions. When a function is called, one or more pieces
of information may be passed to a function, in the form of
parameters. For example, a function used to set the foreground
and background colour of displayed text might accept two
parameters, one for each of the two colour settings. In this
example, a function such as od_set_colour(), would be called as
follows:
od_set_colour(D_GREEN,D_RED);
In this case, D_GREEN, the foreground colour, is the first
parameter, and D_RED, the background colour, is the second
parameter.
In C, parameters are enclosed in parentheses, ( and ), which are
located after the name of the function to be called. Each
parameter is then separated by a comma character. If a function
does not accept any parameters, the parentheses will have nothing
between them. (ie. od_clr_scr() ).
REGISTRATION This is a demonstration version of OpenDoors, which may only be
used under limited circumstances, for a limited period of time.
If you wish to continue using OpenDoors after this "evaluation
OpenDoors Door Toolkit Manual - Version 4.10 Page 197
period", you must "register" it. For more information on
registering OpenDoors, please see chapter 2 of this manual.
REMOTE When used in reference to BBS software or door programs, the term
remote is used to refer to a user or computer that is
communicating with the BBS, for a distant location, by use of a
modem. Compare "Local Mode"
STATUS LINE Usually, the bottom two lines of the screen, as displayed by an
OpenDoors door, is devoted to a status line (although this status
line may be turned off). This status line will display
information about the user who is online, along with information
about the current state of the BBS system, and a reference to the
sysop function keys. See also "Local Window".
SYSOP The term sysop is a short-form for "SYStem OPerator", and refers
to the individual who is responsible for running and maintaining
the BBS system. The sysop is usually the only person who has
direct access to the local keyboard and computer on which the
BBS, BBS utilities and BBS doors are running.
SYSOP CHAT See "CHAT MODE".
SYSOP PAGE Sysop paging refers to the process whereby a user of the BBS
system may call or page for the sysop's attention, when they wish
to "chat" with the sysop, and can be thought of as being similar
to the ringing of a telephone. When a user pages the sysop, the
BBS system will produce some sort of sound, which the sysop may
elect to respond to if they are within hearing range of the
computer. The most common reasons for a user to page a sysop
include the case that they are having difficulty with some aspect
of the BBS, that they have a question, or if they are simply
interested in having a friendly conversation with the sysop.
Obviously, since the sysop may not wish to be disturbed by users
paging at certain times (such as when they are in bed), most BBS
software provides controls to allow you to control paging. These
features might include the ability to set hours for each day of
the week during which paging will be permitted, and the ability
to temporarily override the ability of some or all callers to
page the sysop.
USER When applied to computers in general, the term user simply refers
to any person using the computer hardware and software. However,
when applied particularly to BBSes, the term user refers
specifically to a person who calls the BBS, to carry out
activities such as communicating via messages or chatting,
uploading and downloading files, or using doors. Often, the term
user is used in contrast with the term sysop. In this case, users
are all of the people who call and user the BBS, other than the
sysop themselves.
OpenDoors Door Toolkit Manual - Version 4.10 Page 198
WINDOWS Windows, or MicroSoft Windows, is a computer operating
environment which runs on IBM PC and compatible computers, and
such runs in conjunction with the MS-DOS or PC-DOS operating
systems. This version of OpenDoors can only be used to produce
DOS-mode programs, which will run under DOS, DESQview, Windows
and OS/2.
OpenDoors Door Toolkit Manual - Version 4.10 Page 199
--------------------------------------------------------------------------------
INDEX
--------------------------------------------------------------------------------
A
About This Manual, 20
Access Level, 144
Alias, 137
ANSI Graphics, 30, 112, 133, 193
Archive Contents, 181
ASCII Chart, 70
ASCII Mode, 193
AVATAR Graphics, 30, 100, 112, 134, 193
B
Baud Rate, 125
BBS Information, 126
BBS Name, 132
BBS Systems, 24
Before Exit Function, 152
Box Characters, 152
BPS Rate, 125
Built-In Function Keys, 162
C
Caller Information, 126
Carrier Detect, 35, 86
Chat, 93
Chat Mode, 27, 196
Colour Attribute Codes, 106
Colour Constants, 110
Colour Customization, 164
Colour Functions, 32
Colours, 94, 106, 109
Common Problems, 171
Compiler Errors, 171-172
Compiling With OpenDoors, 21
Configuration Files, 77
Custom Door Info File, 79
Custom Function Keys, 163
D
Debugging, 20, 169
Demo Version, 7
Display Functions, 31,47
Distribution Sites, 176, 179
Door Driver Functions, 31
Door Driver Module, 4, 23, 31, 196
Door Functions, 33
Door Information File, 24, 26, 122, 126
Door Settings, 147
DORINFOx.DEF File, 26
DOS Shell, 27, 152, 172
Download Limit, 136
Drop To BBS Key, 28
OpenDoors Door Toolkit Manual - Version 4.10 Page 200
E
Error Free Connection, 137
ErrorLevels, 27
Example Program - Changing Only Foreground/Background Colour, 110
Example Program - Choosing Text Colour, 107
Example Program - Clearing A Line, 42
Example Program - Dialog Box, 50
Example Program - Door And Utility In One Program, 75
Example Program - Drawing A Window, 100
Example Program - Exiting A Door, 66
Example Program - EZVote, 26
Example Program - First Door, 23
Example Program - Hanging Up In CBV Door, 35
Example Program - Hotkeyed Menu, 73
Example Program - Input Key With Echo, 98
Example Program - Pausing In A Door, 86
Example Program - Setting Door Info File Location, 123
Example Program - Shelling To DOS, 116
Example Program - Terminal Emulation, 63
Example Program - Testing Available Door Information, 126
Example Program - Testing Screen Clearing Capabilities, 43
Example Program - Transferring A File Using DSZ, 117
Example Program - User Statistics Door, 96
Example Program - Waiting For CR, 40
Exiting A Door Program, 65
F
Features, 4
Feedback Form, 19
File Display Functions, 32
FILES.BBS File, 88
Fossil Driver, 24, 197
FOSSIL port, 125
Function Keys, 27, 86, 161
Future Versions, 191
G
Getting In Touch With Us, 174
Graphics Mode, 133-134, 193
H
Hangup, 27
History, 182
I
IBM Colour Attribute Codes, 106
IEMSI Session Information, 129
Inactivity Timeout, 155
Input Functions, 32, 67-68
K
Keyboard Buffer, 39, 86, 98
Keys, 86
L
Language Customization, 165
OpenDoors Door Toolkit Manual - Version 4.10 Page 201
Learning OpenDoors, 23
LIBrary Files, 22
Line Number, 124
Linking, 21
Local Mode, 26, 197
Locked, 5, 197
Lockout, 27
M
Memory Models, 21-22
Memory Swapping, 159
Modem Port, 125
Modem Settings, 125
N
New Version, 182
Node Number, 124
O
od_before_exit Variable, 29
od_carrier() Function, 35
od_clear_keybuffer() Function, 30, 39
od_clr_line() Function, 41
od_clr_scr() Function, 30, 43, 171
od_colour_config() Function, 37
od_control Structure, 25, 120
od_disable Variable, 154
od_disp() Function, 45
od_disp_str() Function, 47
od_draw_box() Function, 49
od_edit_str() Function, 52
od_emulate() Function, 63
od_exit() Function, 23, 25, 65, 152, 153
od_get_answer() Function, 67
od_get_key() Function, 23, 39, 68
od_hotkey_menu() Function, 72
od_init() Function, 24, 74, 122
od_init_with_config() Function, 29, 77
od_input_str() Function, 39, 84
od_kernal() Function, 25, 86
od_list_files() Function, 88
od_log_open() Function, 90
od_log_write() Function, 92
od_page() Function, 93, 158
od_printf() Function, 23, 94, 154
od_putch() Function, 98
od_repeat() Function, 100
od_send_file() Function, 30, 102
od_set_attrib() Function, 106
od_set_color() Function, 109
od_set_cursor() Function, 112
od_set_statusline() Function, 114
od_spawn Function, 158
od_spawn() Function, 116
od_spawnvpe() Function, 118
OPENDOOR.H File, 21, 23, 28
OpenDoors Door Toolkit Manual - Version 4.10 Page 202
OpenDoors BBS, 173
OpenDoors Customization, 150
OpenDoors Distribution Network, 176 - 179
OPENDOORS Echo, 174
OpenDoors History, 182
Our Address, 174
Output Functions, 31
Output Window, 26, 198
P
Paging Hours, 147-148
Paging The Sysop, 93
Pause Key, 156
Phone Number, 137
Printing Manual, 20
Problems, 20
Product Support, 173
Project Files, 21
R
Registration, 7, 9, 13, 17, 174, 198
Registration Form, 11, 17
Running Doors, 24, 26
S
Screen Functions, 32
Screen Length, 143
Screen Width, 144
Security Level, 144
Setting Colours, 94, 106, 109
Solutions To Problems, 171
Source Code, 7, 15
Special Thanks, 192
Status Line, 26, 93, 114, 159, 199
Stop Key, 156
Support, 173
Support BBS, 173-174
Swapping, 159
Sysop Chat, 152
Sysop Function Keys, 161
Sysop Keys, 27, 86
Sysop Name, 131
Sysop Next Key, 28
Sysop Next Setting, 148
Sysop Page, 158
Sysop Paging, 93, 199
System Event, 130
System Name, 132
T
Terminal Emulator, 63, 102, 103
Terminal Emulator Control Codes, 104
Text Customization, 165
Thank-yous, 192
Time Left, 145
Timeout, 86
OpenDoors Door Toolkit Manual - Version 4.10 Page 203
Troubleshooting, 20
Turbo C, 172
U
User Handle (Alias), 137
User Information, 126
User Keyboard Off Key, 28, 39
User Keyboard Setting, 148
User Name, 141
User Password, 142
User Timeout, 86
V
Version History, 182
W
Want-Chat Setting, 146
OpenDoors Door Toolkit Manual - Version 4.10 Page 204
